Want to build a good API? Here's 5 Tips for API Design.

Want to build better APIs that can evolve over time as your system requires changes? Here are 5 tips that will help you change your API design over time without creating breaking changes.

🔗 EventStoreDB

💥 Join this channel to get access to a private Discord Server and any source code in my videos.

🔥 Join via Patreon

✔️ Join via YouTube

#softwarearchitecture #softwaredesign #webapi

[andherium]

00:00 - 00:30 intro
00:30 - 02:25 Where to generate resource IDs (auto-incrementing IDs vs UUIDs)
02:25 - 04:05 Generate meaningful identifiers. (Understandable not just readable)
04:05 - 07:37 Provide meaningful response (that's actually pretty nice)
07:37 - 08:52 Prefer returning a JSON object response instead of an array. This way you leave room for extension.
08:52 - 08:52 Refrain from using technical jargons and prefer language of the domain

---
01:32 Even if you're using auto-incrementing IDs, you could save the order with status "pending" and then return that ID. You could still process the order async.

[maddriven]

very unique tips for api design, this is the first time I have heard of passing the available states in api response. thanks a lot!

[funkenjoyer]

I learned pretty quickly to always wrap the response in an object, that way you can just add new fields to the response and it doesn't break the client because suddenly instead of returning list you return an object

[noideaprojects]

For tip 1, if you are moving the ID up to the API and queuing the persistence, then how errors are handled becomes important and adds complexity. You might be trading the speed of create request time for having clients poll for errors or confirmations the order is created successfully. Does not invalidate the idea, particularly for systems that handle large volumes of requests, but it is a bit of advanced topic/implementation thats needs the developer to apply some thought.

[RasmusSchultz]

an important thing to consider if you add actions, as shown here, is caching - if, for example, the "cancel order" action is only valid for the next 15 minutes, cache expiration should be set accordingly. this can get a little tricky if you have multiple actions with different expiration. part of me honestly likes to avoid this type of problem - in some cases, you might prefer to design endpoints with less data, requiring the client to make multiple, individually-cacheable requests, each endpoint having only one reason to expire and need a refresh. just something to consider. :-)

[allinvanguard]

Really interesting ideas! If there was one thing about API design I'd really love people to stick to, it would also be just sticking to well known REST principles. May it be the design of the URL, or the response. I've seen so many crude apis which e.g. list getting an account as "api/account/getAccount" instead of just "api/account", and modifying entries of a catalogue as something like instead of something like PUT / POSTing to "api/catalogue/<id>/items". Responses are the same. We have well defined status codes and http statuscodes, but a lot of apis would rather return a 200 with a body containing custom enums... It's a mess out there. I wish this stuff was more standardized across the board.

[GabrielSoldani]

just don't roll your own "unique" randomly generated identifiers with less entropy than UUIDv4s trying to make them more meaningful.

also would be helpful to point out that including the actions in the response is called HATEOAS for those trying to read more about it :)

[chinmayghule]

An extremely impressive video. I hope you would do another like this, where you take an API made by a noob like me and make it better. A few implementations and examples of the points you just mentioned would be very helpful.

[RM-xrlq]

dont send a 404 if the request for the content i am trying to get was successful but just empty, just send an empty array

[kabal]

I really like tip 3 & 4. Then using tip 4 to include the available status’ was really cool too.
99% of our APIs are consumed by the same developer who writes them, and via a generated client, but I still think this adds value.

[allannielsen]

We have a rule that if it's a database concern it shouldn't be exposed in the Api. This helped a lot for people to understand why int ids and even guids were not a good idea and helped in creating real business keys for data that migrate across boundaries actually made sense. I think more content creators should help enlighten the benefits of Hypermedia as the engine of application state (HATEOAS) in proper REST api design. Thanks for sharing.

[capability-snob]

This is such great advice - everyone needs to watch this, you've covered everything wrong with the AWS public APIs at least.
One recommendation/alteration I would like to add, especially if this API is specifically for integration, is to use capabilities as your identifier scheme. That is, the opaque part should have more than 16 bytes of entropy and be cryptographically generated. This reduces the need for complex permissions checking in the server and allows integrations to subset access to your objects without having to proxy all requests. Object-capability security has been a long time coming on the web, but videos like this one give me hope.

[PierreThierryKPH]

You're actually describing REST in tip #3 (well, the HATEOAS part of it). It's sad how many people don't know the details of the REST architecture because it is so we'll thought out.

[josephgutierrez]

Great video. These are weird things that only come up I'm certain scenarios but building with it in mind makes your life alot easier in the future if you were to hit those scenarios. Glad this showed up on my feed. Not a video I would have looked for but one I am really glad I watched.

[wisconsin_dotnet]

This is great advice full stop! and another reason that's this guidance important is Security!.. Never send sequential ids to the client. we all know that one logged in user should never be able to see another logged users data with all good intentions however recent security breaches demonstrates discoverability of id leads to information leaks to the tune of millions of users. Security is a topic that deserves it's own dedicated attention and let's explore this more.

[raghuveerdendukuri]

While I used auto-increment id, UUID, etc, I remember considering purpose specific identifiers. I really liked the idea of providing possible actions in the REST API response, nice suggestion, thank you

[rjwhite]

Wouldn’t have thought of a lot of this stuff. Cool video!

[gosnooky]

I pretty much disagree with all of this. A record's ID should ALWAYS be of a consistent affinity across tables. Asynchronously, an autoincrement ID can collide, which is why you should use UUID, GUID or CUID. If you need something human-readable, it should go in a different column, such as "code", (not "order_code", since it exists within the context of an order hence redundant). There is also some advice regarding adding "states" or "actions" being added to a response object. A pure REST API should only return the state of the resource without additional fields. The consuming application should be aware of the possible states, and which actions can be performed under which state, so you can add PUT /orders/:id { "state": "cancelled" } and the API would return the updated resource, or a 415 error if that state can no longer be legally applied to the resource. REST should be a minimal representation of the state of a resource - there must to be some awareness of certain rules/constraints on the client's end whether it's via documentation or something like OpenAPI.

[SajidAli-fntp]

Interesting 3rd point.

In the example discussed, the "CancelOrder" action will not be invoked by the caller immediately after the Order object is returned because in the real world customers don't cancel right after they've placed the order. The order will be cancelled sometime in the future and by that time the "state is pending and the order was placed in the last 15 minutes" condition may no longer be true.

So does the server returning the cancel action really matter aside from making the route opaque to the client?

[Rasecz]

As a Frontend Developer, I like that array of actions there