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.

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

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!

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.

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. :-)

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 :)

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.

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.

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.

What a great video, thanks for the tips, I thought they were really helpful. Also would love to hear more of your thoughts and tips for distributed systems.

this video specially action part on api actually helped me a lot, i was searching for some way to sperate business logic from presentation logic, thanks man

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.

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.

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.

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.

🎉 thanks for your providing your insights! Really liked tip 3 and 5!

These are great inputs...would like more of this contents as these are just few.

Great content! I love this! The whole thing makes sense!

I like tip 3. Nice idea. Thanks! Got a project I've just dont part of where this would be useful so I'm going to add it now.

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

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 "api/catalogue/updateCatalogueWithItem" instead of something like PUT / POSTing to "api/catalogue//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.

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.

Great API Design tips! Thank you!

This is excellent, as always!

Thanks Derek for the tips ❤

Thanks as always for the great content Derek! Regarding meaningful identifiers, this is an interesting tip. My only concern is to be sure anyone in the organization treats it as identifiers and no more, in that case works like a charm. If, for some reason, in some services, someone adds the logic that splits the ID to pickup "CA" and "ON", evolving the ID and making it have a different structure will cause an unpredictable problem in those services. Have you ever experienced something like this?

@3:00 The topic of "understandable IDs" resonated with me. I've always been keen on designing IDs that provide insight into the data's origin or domain just by their format. However, I've consistently been advised against it. Many blog articles emphasize that IDs shouldn't carry business logic and doing so might even be considered poor practice, since their primary function is to index unique rows in a database.

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?

Thanks so much. I like your teaching style.

I wish you expanded more on why you believe IDs should be generated high in the stack for the API to be extendable in the future. I understand the advantages you mentioned but they don't seem related to our ability to expand the API in the future in a backward compatible way. In any case, great video! Well done

Something I would recommend seeing this example is to not call things order->orderID and customer->customerID - it's redundant. It should always (in my opinion) be customer->id and order->id. If you want to have identifying parameters on an object, the advice with a meaningful ID (such as CA-ON-xxx) is good. Stripe also does this (cus_xxyy, pi_xxyy etc.). As an alternative, have a type property with a string that identifies the object's type.

This is a great video. Thanks for the insight! What is an in-depth resource for point three? I have some questions about it as far as implementing best practices, such as: - What is the expectation for clients persisting these actions? I've seen a comment about setting cache expiration, but what about for actions without one? Do clients typically store these actions and query it on their side when coming back in a future session? - Correct me if I'm wrong, but it seems like one of the benefits of point three is to essentially self document endpoints. However, how detailed should documentation be external to the response? For example, obviously, a POST endpoint seems like it should be documented as it's basically the first entry point into a service. However, tying into my first question, is it reasonable to expect a client to not need a GET endpoint documented if they're storing the actions on their side? That feels a bit too imposing upon them to me. However, documenting a GET endpoint for an entity eliminates the benefit of obscuring that URI. I'm sure I'll have other questions as I look into this, so a great resource would be much appreciated. Bonus points if it explains it more casually. Technical documentation is tough for me to read, though paired with a more casual resource would be the best. Thanks in advance!

the message format returned in the cancel order example really reminds me of hal+json. It's a nice iteration from that cuz HAL gets a little crazy honestly

Interesting approach!

Great video. How about the search time on the database if we use uuids as identifiers? Are Databases happier with integers identifiers or they are just fine with uuids too?

Great tips thank you

On the first point, I think it’s better to generate a task Id for the entity if you are creating it asynchronously.

Another very cool video. Generating the ID at the controller/API level is an interesting solution, but I'm going to have to agree with one of the points you made later on: context is everything. Out of curiosity, what do you think of Mike Amundsen's "application/vnd.collection+json" media type for an API? Seems like he's developed semantics for a *very* general API whereas you're proposing custom (but consistent semantics) for any given API. I've seen some harsh criticisms of the collection+json (and even agree with them, to a degree). Do you have any criticisms? That would also make a cool video. Thanks for making these :)

Providing actions and Uri is a great idea, haven't seen that anywhere tho.

Actions as a part of entities is a good one, I'll probably take it into account! But as for states of some props, I'd rather just go for typeset that I could use on front-end in form of Typescript.

You have my follow good man

I would always refer to OpenAPI specifications.. big corp like Microsoft or Google, as well as well build web-based foss projects (unless you want to play around with gRPC or GraphQL)

Although passing actions in the response makes the system very extensible, is there a concern of making the API more fragile, especially for a large scale distributed system? If you’re updating business logic, is it better to make this update explicit with a breaking semver change, and blue/green transition the clients?

The meanful ID CA-ON-#####, how do you prevent collisions across distributed systems? It would be very long to have an id = "CA-ON-" + UUID?

Very unusual tips, forcing you to look on your API from absolutely different point of view. Thanks, that made me think

Great content 👍🏼

I live in Ontario, Canada too! :)

Super useful

I usually agree with all you say but I would never recommend having meaningful concatenated keys as id, it invites to code that uses substring and split to do actual logic on. A big no no. it also leads to y2k like problems where at some point in time an extra character is needed to contain the future info. also when an order is being redirected to for instance an other area where they have it in stock, you will see stupid "citizen developer" systems like BI reports or power apps that use the substring of the id to calculate/group the profit of an area. if you need meaningfull info on your order just add the property itself in the message "Area" : "Ontario", that is a property that can be updated when needed, you can never update the id.

In the example of order canceling, from a UI standpoint, you might want to display a greyed-out cancel button and a reason why an order can't be canceled. If the state was 'shipped' for example, how would you add this? An idea I came up with is the following: ```json { "orders": [ { "orderID": "CA-ON-54812", "status": "shipped", "actions": [ { "name": "CancelOrder", "enabled": false, "reasons": ["status:shipped"] } ] } ] } ``` The front end could then use this reason to find a translation key for the reason it is unavailable, I made it an array in case there might be multiple reasons. Do you think this is a good idea and why/why not? How did you solve this in the past?

🎯 Key Takeaways for quick navigation: 00:41 🆔 *Consider where you generate identifiers (IDs) in a distributed environment to avoid collisions and enable asynchronous processing.* 02:32 🌐 *Generate meaningful identifiers that are human understandable, providing valuable information at a glance.* 04:10 📄 *Include information in API responses about possible actions based on the current state of the system to guide clients on what they can do.* 06:43 🔄 *Embrace evolvability by focusing on actions in responses, reducing client logic changes when business rules evolve.* 08:49 🚫 *Avoid handcuffing yourself by designing responses with flexibility, allowing for additions without breaking backward compatibility.* 09:04 📋 *Use the language of your domain in API design, capturing behaviors and capabilities with terms that make sense within the context.* Made with HARPA AI

Quite interesting 🤗😀

Could you please tell us , about , rate limiting , security , size of an http request , ... how to have an api with high performance and work in high load ...

Instant subscribe.

The thing with the response actions - they're nice, but most clients will ignore them as they likely cannot ingest them. The exception is when you have a configurable, rapidly changing API (though I suggest that is a small subset of cases).

What is your stance on 'dont use guids as id's in sql server' performance wise? Are sortable guids ok?

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

I don’t think there is problem with auto-increment Id building even-driven systems. Like in a transactional and building financial solution environment, you always have unique identifiers like reference which you already have strategy on how you generate it. IDs for me are just for record arrangement in the dbs I am less concerned about that, has nothing to do with the strategy you wanna use to store your data

Just came across the ID issue… would love to understand different strategies for generating order IDs in a distributed database

Is there a name to this pattern where you return the "actions" list with what you can do with the order? I really like this idea and want to read more about it

Passing states and actions in the API response seems nonstandard. What id you want to refactor code? Wont that incur a significant time loss?

Ever thought of getting a lavalier mic Derek. I feel like you're trying to raise your voice unnaturally to get good audio levels when you're in a wide shot without your mic in frame.

I once had to program something up against an API where practically everything used a different name in the API compared to both the domain and what those things were named on the site I was interacting with. That was not fun, but what was even less fun was how the API usage would break every other time I was not looking at it for some time, because they would have updated something, which would then cause the old usage of the API to break. This means that I would regularly have to go and manually walk through their API with their arcane naming, just to check whether things had gotten broken.

A tip for IDs: Use a timestamp, concat it with the user id and the return it encoded in base64. Guaranteed unique, cheap to produce, good with utf-8, can be safely done in multiple locations and doesn't give away internal info about volumes. Downside is that it's obviously a bit longer, maybe 40 chars, and isn't human friendly. But who cares?

i do have some issues with the idea of adding statuses to the list of orders. it feels it breaks the purpose of the endpoint, inflates the payload. i see the benefit of it for rendering the filter without the need to query a different endpoint (GET /order/status) but … that data should be queried only once and then cached, rather than getting it every single time. its not that dynamic that we would need it at every request to be updated… I also would add that not exposing the DB id is a security question too. (and hiding your order volume from your competitors) its just one extra info about your DB which should not be public. (so yeah, use a generated ID) anyway, these are good advices, but i would advise against clumping various list of properties into one call, especially if they are static.

If, you can only cancel an order if it is in the pending status and was created less than 15 minutes ago. You put the action in to the json at the server end. Now the client gets that json and goes to the bathroom for 20 minutes. Now the action is invalid, but since the client hasn't refreshed their call, they can just go ahead and cancel the order, even though it may be too late or the status has changed.

Didn't quite understand what you meant by "URI is completely opaque to the client". Can someone explain? Thanks!

I was hoping to hear something about transactions and rolling back in case of network failures, etc.

Where can I find online jobs to build API endpoints using Django Rest Framework?

What's your take on string vs numbers? I'm leaning towards using numbers only for things that are explicitly intended to be done math with. Often there are e.g. IDs that happen to be numbers but which are for all intents and purposes just character sequences with no mathematical meaning other than perhaps being sortable in the order in which they were created. I think for that one can make a good case to use strings then also for data that currently happens to be numbers, because that autoincrementing integer might at some point in the future become a UUID or some other human-interpretable id.

Don't like actions part.. given your examples with "timed" cancel available and etc. And it's huge security risk to generate URL's for actions, as you actually injecting paths and methods for your API clients to call. All sorts of validations needs to be done before trusting those values received. DNS/HOSTNAME and etc... or u risk leaking your API tokens too.

Good mind bending

Develop for Juniors... Seniors will love you.

If you're generating the IDs at the API level, how do you know that you're not generating a duplicate ID?

putting meaning into unique ID adds complexity to the system, putting the responsibility for this UID before the persistence also adds a LOT of complexity and the payout of speed is probably mostly negligible - one should REALLY make a lot of PoC and non-functional testing before jumping on that train and ONLY if it's reeeeeally needed. Meaning as a prefix is slow and has a cost, meaning as part of the UID generation calls for a service to create that based on some business logic, so it need rules etc... Trusting some part of the system to create UID and pass it down means creating a come-back mechanism when this calls an error and reading messages and reconstructing events...

I don't know if these tips are in the context of REST API (I would think so, because of the examples provided). But using verbs instead of nouns for your endpoints is not very REST. Just something I catch in the video

The actions are added to the model of order? Im confused 😢

I would caution generating meaningful identifiers. You don't want to expose private information via your primary key that's exposed in your client.

Another one is using numbers for statuses rather than words

I don't understand why in the "order" object you have a property "orderId", it is needlessly redundant. This is much better: { "order": { "id": "...", "total": 198.00 "customer": { "id": "...", "name": "..." } }

Meaningful IDs make hacking attempts much easier. Use other fields that aren't used as IDs.

I like the idea to keep URI list on the backend side. I see, we can keep all URI needed for client on the server, and preload it once app has been runned. Also, I see crazy idea: you can send all logic to client side from server xD.

HATEOAS over JSON isn't going to happen, you still need developer documentation so listing the URI & method isn't really useful and is actually harder to work with as it isn't a static string, including an OpenAPI operation name as a "rel" tag would be more helpful. It also doesn't convey WHY an action is or isn't available, if I had one complaint about current "REST" tooling, if you wanted to return an error on cancelling an order in that a client can interpret one of n errors, e.g . order is shipped or past 15 minute time limit current tooling sucks on both client and server side.

And number #6: "When in doubt - leave it out"

Wouldn't meaningful IDs make your table non 1NF due to non atomicity even if it's just informative?

Uuids also have troubles for databases as the index to find records becomes inefficient for being really inefficient Unless you use uuidv1 or ulid but then you expose a timestamp when a record was created. You could make POST a bit more secure against double adding caused by timeouts if the client generates a uuid and return 409 if they try to use the same uuid again Autoincrement integer is possible in distributed systems if you have them increment not by 1, but by the (maximum) number of database servers

I'd like to add not to conflate business logic with http status codes.when I see a 404 not found,it should mean I screwed up royally and sent the wrong URL entirely. it Should not mean teehee order not found

1 tip was rather useless, because it involved a complete architectural change. From monolith synchronous to async event driven. I also not a big fun of tip 4 either, I think it is a mistake. Add a separate endpoint to return information about the API itself. /orders/ -> list of orders /orders/ -> one order /orders/describe -> info about the api, like the available statuses

Thats why i love HATEOAS!

Tips 1: get database data from FE

Passing actions to the api response is not a good way to do it in my opinion. It gives much complexity to the project. Also it would take time and tests is much harder&complex For example if you can cancel the order in 15 min. User knows the cancel url. If request is made to that endpoint, you have to check and validate first 15 min again. Also that continues. I dont like the approach

I disagree about the human understable IDs. They are not flexible enough for system design changes and also gives hackers an extra piece of information when sniffing systems.

Derek, I could not disagree more strongly with tip #2. I have worked many years to get our company’s developers to stop this practice. Here is why: while it might be useful for you to understand the ID, inevitably some developer will parse that ID and use the meaningfulness in their code (even though that same info may be available in the payload). Once this happens, its downhill fast from there. If you change the structure, their code breaks. If you segment like your example (CA-ON-12345), then when you get to the 99999 item, your code breaks. It is just a bad practice and I am really surprised that you offered this as a positive. I love your content and send people to your channel often, but I couldn’t let this one slip by without commenting.

Great Tips . I don't know anyone said to you this. I definitely think if you had a superpower that would be turning into a werewolf

I'm usually a hater when it comes to your DDD content, but this is brilliant, keep it up.

He said a 🥾

Graphql 😅

As a software engineer, I don't really buy any of these man

first video i've seen on the channel. under 2 minutes and i'm already like: a db can generate a guid, an api can ask for the next id from the db asynchronously. i can't trust anything else you're going to say next... you're trying to hard to have content, man.

HATEOS