Good APIs Vs Bad APIs: 7 Tips for API Design

Comment regarding pagination vs cursoring. Pagination grants MUCH more flexability when consuming data, and a well built pagination endpoint also need not necessarily be slow. Cursor based will often force the consumer to go through everything to get a specific piece of data. A well built or poorly built implementation in *either case* can cause issues and slowdown.

Great video! Some key points were highlighted that I hadn't heard anyone else discuss. Thank you!

I was just asked about the idempotancy of different methods during the interview! Well explained!

As always very well explained, thank you!

These visuals are so fantastic. Love your videos and subscribed.

Thank you this was super useful!

00:01 Crafting effective, secure RESTful APIs 00:45 Ensure reliability through idempotent APIs 01:32 Use versioning to introduce new API versions without impacting current consumers 02:13 Versioning for backward compatibility 02:56 Use clear query strings for sorting and filtering API data 03:41 Security should not be an afterthought in API design 04:22 Clear linking and direct paths improve API usability 05:06 Good APIs protect infrastructure and encourage fair use

Very clean explanation.

Thank you for such an informative video.

Really great tips and ideas. And +1 good documentation about authentication methods and possible entities and their fields with its types are a major plus.

this is helpful! Thanks!

Two other tips I want to add regarding Documentation. 1) Make sure you have good, language agnostic documentation. Most API's provide libraries for common programming languages which is great, but there are a lot of languages out there and you can't come up with libraries for all of them, or for future languages. My recommendation is to first write you language agnostic documentation, and then you write your libraries using that documentation, and if there's some information you need that's not in that documentation, then update it. 2) Existing documentation doesn't mean you can be lazy. I work with a lot of FHIR based API's, and despite the fact they all supposedly follow the same standard, there are always a thousand small differences and changes, and very few of them are listed in the vendor's documentation. Remember: Good documentation is an investment. It means less support work for you or your staff, and it means your customers are able to use your API faster, which means they start paying you faster. Bad documentation makes it more difficult for people to use your API, which means they're more likely to give up or look for an easier to use alternative. Rule of thumb for good documentation: If you are the person who is intimately familiar with the API, and you look at the documentation and think "Yeah, that's good enough", no it's not, it's shit. Good documentation should be specific, should be redundant, should have examples. Good documentation, when you the developer of the API, look at it, should make you say: "Do we really need this much detail? Surely it's too much?"

Thank you @ByteByteGo ! I think this might be one of your best videos yet, you packed so much useful knowledge into this one, Thank you!

I will add that these are great advices when you are building a public api. If you are building an api that is basically a backend for a single frontend, you can go easy on these standards and build what you actually needs instead of following blindly the norm.

wonderful, thanks a ton!

Big fan of your book sir. I am new to Architecture. 🙌

Thanks for the video. But I am curious, what tools did you use to create your own diagrams and animations in this video?

Good presentation , May i know what tool you are using to presentation

Another indication to apply the fifth suggestion is that when you share a link with those parameters, the recipient will also have it sorted just as you did.

The top 7 tips: 1) Use clear naming. 2) Ensure reliability through idempotency. 3) Add versioning for backward compatibility. 4) Add pagination for response. 5) Use clear query strings for sorting. 6) Security should not be an afterthought. Use api-headers for passing in tokens. 7) Keep cross-resource references simple. 8) Rate limiting