What makes a great API

I recently did some work on a new ASP.NET Web API project using .Net Core. While doing research and development I could see some themes and patterns on What makes a great API and decided to collate this information.

This was for a RESTful (Representational State Transfer) Web based API (hypertext-driven) with JSON resonse, this was not the API of a new class interface. I dont believe being RESTful makes your API great, SOAP (Simple Object Access Protocol) could work just as well however REST is certainly more popular today. Have a look at SOAP vs. REST: A Look at Two Different API Styles.

For the URI format see HTTP verbs.

Pillars

Clear pillars are needed for a great API, this is certainly not an exhaustive list but these stood out for me.

Security

Dont bolt security on at the end, secure your API from the start.

  • Use OAuth 2.0 for authorization
  • Never put stack traces in responses, this can disclose sensitive information
  • Errors must be represented in Problem JSON (RFC 7807) format, providing error type (URI), and optionally title, status, detail along with others.

Supported & Well Architected

  • Use the OpenAPI specification
  • Later updates to the specification can be done at editor.swagger.io
  • Document the API first as a proposal and then implement the empty controllers and Generate the OpenAPI specification via Swashbuckle. Use the generated specification to test that the implementation respects the contract.
  • Write API documentation and build API client SDKs (Software development kit)
  • Utilize patterns, standards, templates, and frameworks to realize the features of an API which are not domain specific.

Consistent

  • Be stateless
  • have a common look and feel
  • The number of items returned by a collection must be limited and paginated (Sorting & Paging)
  • Fielding defined appropriate use within HTTP of the canonical verbs GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. So don’t change state with GET :)
  • Search by criteria, examples
    • /audits/date?start=&end=
    • /audits/search?q=foobar
  • HTTP header Fields should be in Hyphenated-Pascal-Case format
  • Date and Time values must be represented as YYYY-MM-DDThh:mm:ss[.sss]Z format strings.
  • Dont use null for any represented types
  • Resource endpoints must use plural resource forms, example /foos
  • Resources and sub-resources must be hierarchically identified, examples
    • /{resources}/[resource-id]/{sub-resources}/[sub-resource-id]

Performance

  • Allow to scale horizontally by using Docker containers and orchestration software like Kubernetes
  • Rate limit client requests using HTTP Status Code 429 Too Many Requests

Ability to change

  • Avoid breaking changes, dont remove fields/methods/add additional validations

References