❓🐞 ALM APIs: Many inconsistencies in endpoints, headers & options... doesn't match existing SharePoint REST API patterns

[andrewconnell]

Category

• Question
• Typo
• Bug
• Additional article idea

Expected or Desired Behavior

The SharePoint ALM APIs should follow generally accepted REST practices / OData protocols and at the very least, mirror what has already been adopted with existing SharePoint REST APIs.

I love the ALM APIs, but these inconsistencies are disappointing and frustrating. IMHO, it feels like a rogue team built these APIs without taking into account the established APIs that came before them... this will hurt adoption of the ALM APIs... many of the choices by engineering are confusing.

Observed Behavior

• Inconsistencies when working with items in collections

  to get a specific app, you use the endpoint ../_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

  • Feedback-1: Why have a GetById() method? Existing SharePoint REST APIs use the pattern /collection(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx)
  • Feedback-2: When passing GUIDs, we've always had to specify the type... why the omission of the "guid" word... even using the current endpoint, it should be ../_api/web/tenantappcatalog/AvailableApps/GetById(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx') to match what other endpoints use

• Presence of X-RequestDigest

  Why do we have to pass the X-RequestDigest when doing certain operations when we are already authenticated and passing a valid access token?

  BTW, this isn't shown in the docs

• HTTP Header CONTENT-TYPE requires charset

  Even though the docs don't show it, when you send data sometimes you have to specify the CONTENT-TYPE... but simply passing in a valid OData 4 value such as application/json;odata=nometadata doesn't work... it requires the extra charset=utf-8... WHY?

  BTW, this isn't shown in the docs

• Inconsistencies when working properties on operators

  In the case of adding a package to the app catalog, you specify if you want to overwrite it and the name of the file in the endpoint: ../_api/web/tenantappcatalog/Add(overwrite=true, url='test.txt').

  Yet, when you want to deploy, you use the endpoint ../_api/web/tenantappcatalog/Deploy which has an option where you can skip feature deployment... however you don't specify that option like a method call as Add does... instead you have to pass it in as a JSON object as part of the body in the request. Why is this inconsistent?

  Please pick one... while I'd prefer submitting a JSON object in the body, I'll accept the way the Add operator does it, just be consistent.

• Non-Standard Header when Uploading Packages

  When uploading a package using the Add operator, you tell the API that binary data is in the body, but not using the standard CONTENT-TYPE: multipart/form-data option when uploading data... you have to use the custom header binaryStringRequestBody:true that doesn't even have the X_ prefix to indicate it is custom. I get this has history with SharePoint APIs, but why not follow standards?

[VesaJuvonen]

thx @andrewconnell for getting the issues listed. This is a good list of improvements to be addressed on our side. Appreciate work around defining the issue details cleary on this one. We'll get this processed more detailed in upcoming days.

[github-actions]

Thank you for taking the time to file an issue. We periodically archive older or inactive issues as part of our issue management process, which automatically closes them once they are archived.

If you’d like to understand more about why and how we handle archived (closed) issues, please see Our approach to closed issues.

We appreciate your contribution and if this is still an active issue with the latest SPFx versions, please do resubmit the details. We needed to perform a cleanup, so that we can start with a clean table with a new process. We apologize for the inconvenience this might cause.