Guidance for API Development

Manish Jain
2 min readMay 30, 2020


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:



Manish Jain

Cloud Architect and Software Engineer