Creating a new API
What is the process for designing and building a new API?
My last API I just jumped straight into a new project and started building endpoints. Now I have to make a new one and I am wondering if I should first define the endpoints using OpenAI specification or something? This one is going to be used by external users so I want to get it right with versioning and documentation.
I am also thinking about using Azure's Api Management https://learn.microsoft.com/en-gb/azure/api-management/api-management-key-concepts
Azure API Management - Overview and key concepts
Introduction to key scenarios, capabilities, and concepts of the Azure API Management service. API Management supports the full API lifecycle.
8 Replies
Usually, you build the API and then use NSwag/Swashbuckle to generate the spec
Not the other way around
Ah I see, well that's how I done the first one so on the right track then 😄
Are there any fast track ways of doing it? Building endpoints is quite a tedious and repetitive job 😩
and is there a specific pattern I should follow? I guess
items/get for all
and
items/get/{id} for details of one?GET: /items
GET: /items/{id}
Don't place the HTTP verb in the URL, it's useless
Also, ideally, you wouldn't actually get all the items, but use pagination instead
GET: /items?page=2&perPage=25 or GET: /items?after=5261&count=25 or some such
Depending on the kind of pagination you wantah yes ofc.
GET: /items?page=2&perPage=25 is the one I'd go forFor a brand new API, I start by features, then break my features down into endpoints. This is usually done on a whiteboard or in a text document. When I know roughly what I want and need, I start coding
For a public API with external users, you 100% must think about versioning from the start. You can do versioning in the URL (recommended, imho) or by headers, and there is an official api versioning package iirc
There is not going to be that many endpoints really, 90% will be GET too, because it's really just for them to see the info we have.
But yeah I do 100% need versioning 😄
You can still use Postman to view your spec as it works just like swagger
It works akin to SwaggerUI
Swagger is what generates the OpenAPI spec
SwaggerUI is what consumes the spec and displays a nice documentation page with the ability to call the endpoints
(also, Postman fell off, Insomnia fell off, dunno about Nightingale, Bruno is cool)