Reference implementation REST API

[istibekesi]

Question: Is there any reference implementation of the Microsoft REST API Guidelines publicly available?

(I’ve checked the GitHub API, but I’ve noticed slight differences. For example, GitHub uses PUT, for submit a command, instead of POST)

[JeffreyRichter]

The older guidelines were implemented haphazardly and are still used for M365 services.

However, we actively work on and update the Azure REST guidelines:

• Azure services that have already shipped will continue to work as is (and not follow these guidelines) because we do not want to break customers.

• When an existing Azure service introduces new features, they follow their exiting patterns to be consistent within the service.

  • However, if the old pattern had problems, then they will not follow the problematic pattern and will adopt the newer guidelines.

• New/Greenfield Azure services adopt the latest guidelines.

A newer service to look at is Azure Communication Service (ACS). There are several other newer services as well.

[istibekesi]

I’ve checked the Azure Guidelines and compared them to one of the ACS service references you recommended to look at.

A few questions came to my mind that could help me see if I understood the guidelines correctly.

• POST {endpoint}/chat/threads
  • Does the same JSON schema for POST request/response not apply to this endpoint?
  • How do I identify field field mutability in this endpoint? Is 'participants' an update field? Is 'invalidParticipants' a read field?
  • Are 'participants.rawId' and 'communicationUser.id' the same? What is the purpose of having both?
• POST {endpoint}/chat/threads/{chatThreadId}/participants/:add It seems to be an action, so shouldn't it return 200 instead of 201? Why having / between the resource and the action? /participants/:add vs /participants:add?
• POST {endpoint}/chat/threads/{chatThreadId}/participants/:remove It seems to be an action too, so shouldn't it return 200 instead of 204?
• POST {endpoint}/chat/threads/{chatThreadId}/readReceipts It creates a new resource, shouldn't it return 201 along with a location header?
• Is there any reason behind placing create, delete, and list under the "Chat" group and read, update under the "Chat thread" group for chat CRUDL in the docs?

[JeffreyRichter]

• POST can be used for resource creation (although we strongly discourage this and strongly prefer PATCH instead). When used for resource creation, the request & response bodies should be the same.

  • You can indicate in JSON schema which fields are read-only and which are not

• POST can also be used for RPC-like actions (not resource creation) and in this case, the request & response are always different like how a method's inputs and outputs are completely different.

  • In this case, it doesn't make sense to mark any fields as read-only because the input & output schemas are completely different.

• Are 'participants.rawId' and 'communicationUser.id' the same? What is the purpose of having both? [JR] I'm not an ACS expert. As this is a domain-specific question, you need to ask them. It is definitely our hope that teams use great names consistently when designing their API contract - I hope that was done here too.

• POST-actions should return 200; not 201. If this returns 201, that is probably a bug.

• At one point our guidelines said to use "/:". We have since removed the last "/" but ACS is grandfathered in as using the "/". If we were starting ACS from scratch today, it would be "/participants: add" (no slash before colon.

• About "/:remove": Yes, 200 is preferred over 204 as it is not breaking to return 200 with a {} JSON body that can add fields in the future. Returning 204 with no body today and changing this to 200 with a body tomorrow can be breaking for some SDK languages and for clients specifically looking for 204 today will not see 200 tomorrow. This may also be a bug and 200 should be returned but it is breaking to fix that now. Hopefully, the operation will NEVER have something to return.

• About "/readReceipts": 201 is OK and clients MUST also treat 200 as OK as the POST operation can be retried and this is why repeatability headers are required for POST-resource-create operations. Yet more reasons why we don't like POST for resource creation. The response can (and should) have the newly-created (read-only) resource id as a field and this is enough for the client to construct the full URL to the new resource. A Location header is not required.

• You'd have to ask the ACS team as it is domain specific. I suspect that they expect their customers to find the things they are looking for more easily.

[rszabolcs]

It's a really interesting conversation. If I may ask as well, can you mention an example where PATCH is used for resource creation? The examples I skimmed just didn't.

[JeffreyRichter]

Here's an example, see https://[raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/agrifood/data-plane/Microsoft.AgFoodPlatform/preview/2023-06-01-preview/agfood.json](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/agrifood/data-plane/Microsoft.AgFoodPlatform/preview/2023-06-01-preview/agfood.json)

Some of these resources have PATCH (without any PUT) and the docs for PATCH says: "Creates or updates an application data resource under a particular party." (for example).