Best Design Practices — .Net Core Web API
When it comes to API design, there is no silver bullet that will solve all your needs. You need to be aware of generally accepted design practices but design around you specific needs. Here is my list of generally accepted best practices.
Before diving into generally accepted practices for API design, please read about HTTP and REST for a quick refresher.
- Design with intent, get feedback for each iteration of design.
- KISS (Keep it Stupid Simple)
- Design resource oriented APIs (REST).
- Be consistent with resource naming.
- Generally plural nouns are used instead of singular nouns or verbs such as:
— /v1/employees → Employees collection resource
— /v1/employees/1 → Employee with ID:1
- As a sub-resource strategy do not go more complex than collection/item/collection such as:
— /v1/employees/1/shifts
— /v1/shifts/55/employee
otherwise the sub-resources became too complex and harder to manage. Instead think about including links for related resources in returned response. (REST — HATEOAS)
- Be careful about the URI length, some servers or clients may have problem parsing identifier lengths over 200 characters.
- The client should not be exposed internal mechanics of API. A resource might have several entities underlying but client should receive the resource as a single business entity.
- The balance between large number of small resources (too much server load) and a resource that contains too much information (too much bandwidth consumption, latency) should be tuned according to business needs.
- Select a subset of suitable HTTP status codes instead of trying to utilize every status code.
- Do not mutate your data with GET requests.
- Consider if you need sorting/filtering/ordering.
- Always validate the models received.
- Think about reporting error messages in a way that is easy as possible for your API consumers to find and fix errors. Example:
— If a required property or properties are missing for a POST request;
— — State which property or properties are missing
— — State the error message
- Document your API!
- Version your API!
- Include unit testing for you API!
- Again remember, you do not need to follow any of the best practice blindly, you need to come up a design according to the business needs. Your API design can be suitable for your needs even if violates every accepted best practice.