How to Design a REST API That Doesn’t SUCK

Learn 6 essential tips for designing a great REST API that even big companies often overlook. From following standards and maintaining consistency to writing clear documentation and simplifying integration, this video covers everything you need to create user-friendly and efficient APIs. Don't miss out on the key strategies for improving your API design!

🎓 Courses:

👍 If you enjoyed this content, give this video a like. If you want to watch more of my upcoming videos, consider subscribing to my channel!

Social channels:

👀 Code reviewers:
- Yoriz
- Ryan Laursen
- Dale Hagglund
- Kit Hygh
- Alexander Milden
- Bean

🔖 Chapters:
0:00 Intro
0:47 Tip #1: Follow the standards
4:09 Tip #2: Be consistent
5:59 Tip #3: Keep things simple
8:35 Tip #4: Write clear documentation
10:41 Tip #5: Make sure your API is easy to navigate
12:55 Tip #6: Make integration easy
20:57 BONUS tips
22:19 Mea culpa
23:01 Outro

#arjancodes #softwaredesign #python

DISCLAIMER - The links in this description might be affiliate links. If you purchase a product or service through one of those links, I may receive a small commission. There is no additional charge to you. Thanks for supporting my channel so I can continue to provide you with free content each week!

[acmethunder]

Standards and Easy integration are probably the most important. For example, if an API is going to accept a standardized data format (like JSON), FOLLOW THE SPEC!! (Authorize Net, I'm looking at you!!)

[KeithFlint]

I'm looking forward to see more videos about the design. Like general concepts. I learn all programming by myself and after a short period of time I realise, that I'm developing a Frankenstein that's gonna eat me in a while. I build mess 😂

[sebastiannarvaez]

We need a video to learn how to develop the SDK, please

[sambroderick]

The time/date standards are complicated but are handled in the base library in Python plus additional packages (probably the same for js). There are a lot of transactions so requiring seconds is probably a performance issue.

[RandomHammy]

Anyone watching this video, ignore all of Arjan's comments on Paypal's use of ISO-8601 datetime format. That is a *financial* and *developer centric* API, so it *requires* arguments to be *as accurate as possible*. The use of the ISO format:
- Guarantees an international standard
- Guarantees easy datetime parsing and construction in almost all modern programming languages (python is one of the few oddballs that didn't follow international standards on datetime strings for some daft reason)
- Guarantees cross time zone accuracy

While Arjan is correct in saying arguments in APIs should be simple and easy to use, this is one of the worst examples to give! Datetimes in financial transactions are just one of those things where accuracy is a pivotal Functional Requirement

[vgrigori]

@ArjanCodes Thanks for the video. I have two questions: 1. What do you think about swagger for api documentation?
2. How do you like to use POST instead of GET in case of multiple search filters?

[rednax]

This video came at just the right moment. Preparing some API s for a system, these tips will be implemented immediately. Thanks Arjan.

[soklagenhet]

It would be interesting if you created a video or course about structuring a fastapi application. E.g, how would you structure the endpoints (model-focused? domain focused?), how would you handle business logic?

[bla]

10:21 I can reassure you that being in the field doesn't help with understanding what this means...
Because I can see fields related to corporate bonds, but also to foreign exchange. So the API is mixing asset classes even though the name suggests it should only contain currencies. Complete nightmare to work with!

[therealjohnshelburne]

You’re a legend! Pointing out which APIs are great vs. sht is so helpful

[ulfjohansen]

The fact that you write applications that don't care about proper representation of time is just an admission that you don't actually work in the real world. Using anything other than a proper standard representation of time in a api that is used globally would be crazy. Somtimes things are not as simple as it is with your hobby projects.

[GamersOutcast]

Quickly becoming the best coding channel. $10 for pro is too little I think its worth more than that. You should add supporter their for more than 10 I would get it in a heartbeat the value is already there.

[PhunkyBob]

I see a lot of sites providing a panel with example for various languages (cURL, Python, JS, ...) as input and corresponding result for every endpoints.
Is there a way to generate this panels automatically?

[Cohnan]

You read my mind. I had been thinking about finding resources on what a good API should be

[oncedidactic]

re: custom data, off the top of my head similar to video's approach with some dfiferences:

Use postgres json data type to store actual json (the custom data dictionary). That's already one step better than string storage with parsing.

Then you can choose whether to do mutation logic in postgres itself with custom functions, or do that in the python layer. Either way, you need something that can merge json without dumb overwrite behavior, and avoid putting that chore on the API user's back. (As you mentioned.)

Probably the easier/cleaner path at first to due all the mutation stuff in python and use postgres purely for storage with vanilla IO. Hopefully you can leverage python syntax to make this pretty breezy. i.e.
custom_data = getdata(id)
new_custom_data = req_body["newdata"]
merge_data = # <--- this is the happy python part using update() for ezpz
updatedata(id, merge_data)

And you can add more intelligent handling of things like lack of keys on new data, should that delete those keys on the saved dict? Maybe add flags on the request like "merge", "overwrite", "version" etc. to specify the behavior, like keep a "log" inside the custom data of last 3 saves of that dict key, by numbering them.

In any case python is the "right" place for this fanciness, but you could make it all in postgres using a custom function too, and then hide that complexity from the API layer and let the DB handle it. While it may seem complicated, if you are comfortable with SQL you can easily unpack both jsons into table structures, then do JOIN and UPDATE statements to recapitulate the same logic as dict merge very naturally. Or you can even write a plpython script as the function and then there's almost no difference.

Anyway the payoff of all this is that the concept in the API layer of "custom data" field is now just very simple -- it's a dict / json, just use it as you'd generally expect. Add more OOP if your codebase benefits but not necessary.

[oncedidactic]

I can see why PayPal API would be intentionally designed to force use of fully granular arguments re: datetime (including seconds and timezone). It's an interesting pivot point here between "keep it simple" and "use obvious default behavior" vs safeguard the user against dumb logic errors especially where there are possible gotchas. (How you handle datetimes is a classic source of headache.)

But this actually serves your broader point -- it should ALWAYS be as simple as possible. There should be a good reason why it's not as simple as you might think at first. And that reasoning should be explained well, and made obvious through example code. AKA "as simple as possible" might not mean "as easy as the novice thinks of it", and the required complexity then needs to be surfaced directly.

[roberttaylor]

Thanks! This is was great coverage of the subject.

[Nalewkarz]

Hmmm.. I didn't get the part with adding ids of related object. Isn't that obvious that You should provide only needed data (it means that related objects will be usefull only for chosen use cases) ? And then, when it's needed You can always return not only ids but also aggregate (more detailed information about related objects) . Input and output serializers (or input and output dto's) are also next big thing You missed. I liked that you showed real API's examples.

[abomayeeniatorudabo]

I know private methods isn't a really python thing but I would have used the _ naming convention for methods I'll use only inside the class.

[not_a_human_being]

While that all nice and dandy, I have a felling that some basic CRUD must be "out-of-the-box" experience.. like plug in your custom functions here and there and get an API (is there a package like that? gotta be somewhere..), at least for CRUD on objects that customer "owns".