Guidance for API Development

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

  • 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 url design, then request and response objects/properties, think names for the url, source code projects, git repo, cloud services, plural vs singular for each, casing etc.
  • Write a service per domain (an entity or a set of related entities) (DDD — not micro, not monolith).
  • You can call services internally to operate on dependent/related entities.
  • 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.
  • 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 200 OK.
  • HTTPS/Secure/Basic Auth in simple scenarios or oAuth for external APIs.
  • JSON casing — preferably camel or snake casing.
  • Swagger/Developer portal and/or provide postman collection to your API consumers.
  • Return appropriate HTTP codes, but don’t overthink specific codes, you can start with basic ones.
  • Don’t be too hard on nouns; 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 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 400 bad request.
  • URL versioning is usually more explicit than headers are.
  • Enable CORS.
  • Enable HTTP2.
  • Deploy on cloud in a simple deployment model first (paas — azure app service, aws ebs, gcp app engine).
  • Need more tighter control/customizations on deployments? It’s complex: use container registries/docker/kubernetes. You probably won’t need it.
  • 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.
  • For new projects, think about independent databases for your microservices.
  • There is a lot of information/confusion/buzzwords with APIs, especially for a beginner. Start simple.

My preferred tech:

  • .net core stack
  • MEAN stack with typescript

Find more information at 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

Cloud | Web | Mobile | DevOps — Consultant