.NET core is great for creating a Web API project to provide an API.
Tip: Swagger is a great tool that has an editor to specify your API. With the OpenAPI specification for your API, you can generate documentation, or use the code generation feature to generate tests or C# code.
Tip: Use the Swashbuckle.AspNetCore Nugget package to generate an OpenAPI specification for your API if you use a code first approach.
Tip: Swagger is a great tool that has an editor to specify your API. With the OpenAPI specification for your API, you can generate documentation, or use the code generation feature to generate tests or C# code.
Tip: Use the Swashbuckle.AspNetCore Nugget package to generate an OpenAPI specification for your API if you use a code first approach.
Do not trust incoming parameters, you must validate. Always respond with generic header error messages so you don't give away back-end information. Ensure you log all errors and review them.
 |
| Preferred High Level Design I like for Web API projects |
The API needs to return Status Codes to allow consumers/clients to know how there operations are doing so I design with these standard HTTP status codes:
- The bold codes are the three minimum set of response codes I will use for a simple API. The next 4 most important are italicized.
- Name resources/EndPoints with nouns and I always use lowercase e.g. /api/customers is better than verb noun which was common a few years ago, e.g., /api/GetAllCustomers NB! No verbs in URL naming.
- Keep the URL's simple.
- Always use HTTPS.
- DateTime data is always in UTC.
- Sensitive information must be in the header or body, not in the URL as it is not encrypted.
URL/Resource | GET (read) | POST (create) | PUT (Update) | DELETE (Delete) |
/customers | List all customers | Add/created a new customer | Bulk update customers | Bulk Delete or Generally error and don’t implement |
/customers/35 | Get a specific customer. Customer 35 is John Doe | NA | Update the John Doe record | Delete the John Doe object/record |
HTTP Methods to Support
| GET | Return the current value of an object | |
| PUT | Replace or update an object | |
| DELETE | Delete an object | |
| POST | Create a new object. Return 201 for created and 202 for long running operations. |
Versioning
API's need to change but there can be multiple client applications consuming my OpenAPI. We use versioning to ensure I don't break existing implementations. There are different strategies for versioning API's:
API's need to change but there can be multiple client applications consuming my OpenAPI. We use versioning to ensure I don't break existing implementations. There are different strategies for versioning API's:
- No versioning: https://pbeck.co.uk/customers/35
- URI versioning: https://pbeck.co.uk/v2/customers/35
- Query string versioning: https://pbeck/customers/35?version=2
- Header Versioning: Not in the URL but passed in the header (my preferred option)
Tip: Enforce versions are present in the header. No version return bad request.
JSON
JSON property names SHOULD be camelCased.
JSON
JSON property names SHOULD be camelCased.
Query Params
Allow filtering using query param e.g. https://pbeck.co.uk/customers?firstname='paul'
Allow sorting for the most common properties
DateTime should be in UTC - The pattern for this date and time format is YYYY-MM-DDThh:mm:ss.sTZD. It is recommended to use the ISO-8601 format. UI does adjustment for local time display.
Paging
Requests must have max return limit e.g. 100 items. Specifying the limit param if you want to change the size of the dataset to return.
CORS
Cross Origin Request will need to be supported, reply on OAuth for who can use the API.
HATEOAS
HATEOAS
Good way to navigate around your API. And a principle worth adhering to where possible.
Authentication and Authorization
API's access should be via OAuth2.0. It is very easy to hook APIM and underlying App Service (Web API) up to AAD B2C. Scopes are used for authorization.
Code Review/Quality
"Linting is the automated checking of your source code for programmatic and stylistic errors. This is done by using a lint tool (otherwise known as linter)". Examples of Linting Tools are Resharper, StyleCop, SonarQube, ...
Security
Security
Always review the OWASP API Security for your API's.
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
https://owasp.org/www-project-cheat-sheets/cheatsheets/REST_Security_Cheat_Sheet.html
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
https://owasp.org/www-project-cheat-sheets/cheatsheets/REST_Security_Cheat_Sheet.html
It's a good idea to also have a WAF in front of your API.
