Sunday, 12 May 2019

Designing an API with Web API on Azure

.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.
Do not trust incoming parameters, you must validate.  Always respond with generic header error messages so you don't give away backend 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:

CodeCode Status Meaning
200OK (GET)
201Created (POST or PUT)
202Accepted.  Used for long running operations.
204Resource has been deleted (DELETE)
304Not Modified
400Bad Request
401Not Authorized
404Not Found
422Entity Validation Issue
429Too many Requests (Implement at APIM layer only)
500Internal Error

The bold codes are the minimum set I will use for a simple API.
Always use HTTPS and sensitive information must be in the header or body, not in the URL as it is not encrypted.

API's need to change but client applications consuming my Web API need to use versioning to ensure I don't break existing implementations.  There are different strategies for versioning API's.  I like to keep it simple.

  • No versioning:
  • URI versioning:
  • Query string versioning: https://pbeck/customers/35?version=2
  • Header Versioning:  Not in the URL
I like to use no versioning for simple API's that are easy to manage and unlikely to change and URI based versioning for more complex API's.  APIM has a great implementation for versioning.  Generally adding optional data is pretty safe for API versioing, and obviously you need to give 3rd parties using your API's time to imeplment the new version before deprecating and versions.

HATEOAS - Good way to navigate around your API.  I've only used this concept once in an early design on a project that I did not see the end result.

Authentication and Authorisation
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 authorisation.


Post a comment