How to Design a REST API That Doesn’t SUCK

💡 Get my FREE 7-step guide to help you consistently design great software: arjancodes.com/designguide

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

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

APIRoast 🔥

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 😂

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?

@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?

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.

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

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

Hi Arjan, your videos are as always precise and insightful. I have a question: I am currently doing a project that requires at the end of the execution to push 20-25K rows of data mssql server (on premise). I used sql alchemy, was bit slower. later I used pyodbc, bit faster. Now approx. it takes 3 minutes to push 4k rows. My data has 20 columns, including int, varchar, and bit types. Would you suggest something, that could make the pushing faster, maybe each time with a chunks of 100-150 rows?

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

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

Thanks, Arjan!

What about making a test framework / sandbox for unit testing your API?

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.

Thanks! This is was great coverage of the subject.

PayPal documents that it has a delay of up to three hours between something being entered and appearing in the search results. You don’t mention the other handlers. Do they explicitly say the response is instant (or has some shorter period)? Or are you assuming that their lack of statement means that it is immediate? Have you tested them? Are you truly this naïve?

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.

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.