Guidance for API Development

Here are some quick tips and recommendations for designing, developing, and deploying HTTP based public/private APIs (called REST APIs or microservices endpoints):

• Start simple, don’t over-engineer.
• Remember the basics — resource-based design, CRUD operations, idempotency, stateless calls, HTTP verbs, etc.
• Chatty vs. Chunky — who’s your consumer? Mobile app, web, system integration? Design accordingly.
• When designing: start with the url design, then API contracts (request and response objects/properties), source code projects, git repo, cloud services to use, plural vs singular for entities, casing etc.
• Write a service per domain (an entity or a set of related entities)
• You can call services internally to operate on dependent/related entities (for example service-to-service communication).
• All APIs should be fast and return the response to the client immediately. It can queue on the back end for long-running processes.
• Plural vs. singular resource names: Do you support plural for a particular entity: for example api/v1/orders/1 or api/v1/customers/123/orders/567 vs. api/v1/dashboard is singular.
• GET — additional filters with querystring, no PII on querystring. For filtering array, return [] when no items are found (as opposed to 404 not found). For a single item, return 404 not found if no item is found.
• POST — return newly created object with code 201 created.
• PUT or PATCH — idempotent — return an updated object or empty response based on your preference.
• DELETE — idempotent — return 2XX OK.
• Use HTTPS/oAuth to secure the APIs.
• JSON casing — preferably camel or snake casing.
• Swagger/Developer portal and/or provide the Postman collection to your API consumers.
• Return appropriate HTTP codes, but don’t overthink specific codes, you can start with the basic ones.
• Use nouns for the endpoint resource that works 90% of the time but in real life, you may have an entity that is not a noun or have a mapping entity that represents many entities. As long as you can perform the CRUD in your system and its required (by the clients/system), it can be considered a REST resource.
• Return required field/data type/business rules validation errors all at once with the 4XX bad request.
• URL versioning is usually more explicit than header versioning.
• Use Cloud API gateways, especially for public APIs.
• Support bulk operations/updates (optional).
• Don’t overdo microservices, be careful with the breakdown. For monolith classic services conversions — think macro first.

To find more information check the following links:

https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design

https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md