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.
Clear pillars are needed for a great API, this is certainly not an exhaustive list but these stood out for me.
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
detailalong 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.
- 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
OPTIONS. So don’t change state with GET :)
- Search by criteria, examples
- HTTP header Fields should be in Hyphenated-Pascal-Case format
- Date and Time values must be represented as
- This is ISO 8601
- Dont use null for any represented types
- Resource endpoints must use plural resource forms, example
- Resources and sub-resources must be hierarchically identified, examples
- 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