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 optionallytitle
,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
, andOPTIONS
. 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.- This is ISO 8601
- 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
- https://swagger.io/resources/articles/adopting-an-api-first-approach/
- https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api
- http://spec.openapis.org/oas/v3.0.3
- https://tools.ietf.org/html/rfc3339
- https://tools.ietf.org/html/rfc7807
- https://www.elastic.io/6-characteristics-of-great-api/