How to Design Better APIs

The error messages could be better yet.<p>The example uses a different code per issue, for instance: &quot;user&#x2F;email_required&quot;. Most integrators will build their UI to highlight the input fields that contain an error. Making them parse the `code` field (or special-case each possible code) is pretty toilsome.<p><pre><code> &#x2F;&#x2F; from blog post { &quot;code&quot;: &quot;user&#x2F;email_required&quot;, &quot;message&quot;: &quot;The parameter [email] is required.&quot; } </code></pre> Make it parseable:<p><pre><code> &#x2F;&#x2F; improved { &quot;message&quot;: &quot;An email is required.&quot;, &quot;error&quot;: &quot;missing_parameter&quot;, &quot;parameter&quot;: &quot;user.email&quot; } </code></pre> In addition, I:<p>* rewrote `message` to be an acceptable error message displayed to (non-technical) end-users<p>* moved message to be the first field: some developer tools will truncate the JSON response body when presenting it in the stack trace.<p>---<p>As an added bonus, structured data allows you to analyze `error` frequencies and improve frontend validation or write better error messages: <a href="https:&#x2F;&#x2F;twitter.com&#x2F;VicVijayakumar&#x2F;status&#x2F;1495092161821429761" rel="nofollow">https:&#x2F;&#x2F;twitter.com&#x2F;VicVijayakumar&#x2F;status&#x2F;149509216182142976...</a>

Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server.<p>Sure, there is gRPC, but it requires another API specification (the proto files).<p>There I said it. HTTP Verbs constrained REST APIS are the worst thing ever. I hate them.<p>They introduce un-necessary complexity, un-necessary granularity and they almost always stray away from the &quot;REST principles&quot;. To hell with &quot;Hypermedia&quot; stuff.<p>I find it such a joy to program in server rendered pages. No cognitive overhead of thinking in &quot;REST&quot;.<p>But, of course, all this is only where the client and server are developed by the same person &#x2F; company.<p>For publishing data and creating API for third party use, we have no serious, better alternative to REST.

Some nice tips in here. However, tip 15, I strongly disagree with:<p>&gt; 15. Allow expanding resources<p>I would suggest the opposite. A REST API should not return nested resources at all. Instead, and to stay with the example provided on the website, to obtain the &quot;orders&quot;, the &#x2F;users&#x2F;:id&#x2F;orders endpoint should be called.<p>It might be tempting to return nested resources, because clients would only have to make a single call.Technically this is true but once the domain of your API starts to grow, you will find that the interface will become increasingly muddled.<p>The suggestion provided (use query parameters) is basically a work-around. If you want to offer this to your clients, front your REST API with a GraphQL API instead. It is literally the problem that GraphQL solves. Keep your REST API clean and dumb and focused around CRUD.

Can someone share how they handle versioning in their API when it comes to data model changes? For example `POST &#x2F;users` now takes a required field `avatar_url` but it was not part of `v1`.<p>Since this field is validated in the DB, merely having `v1` `v2` distinction at the API layer is not sufficient. So I was thinking we will have to either 1) disable DB validations and rely on app validations or 2) run two separate systems (e.g., one DB per version) and let people &#x27;upgrade&#x27; to the new version (once you upgrade you cannot go back).<p>Even though people refer to Stripe&#x27;s API versioning blog, I don&#x27;t recall any mention of actual data model changes and how it is actually managed

a) Use standardized error codes, not standardized error messages. Clients are responsible for internationalization, which includes presenting error messages in the user&#x27;s language. If you document a set of error codes as an enum, the client can present a user-friendly error message in the user&#x27;s language based on the error code. If there are dynamic parts of the error message, i.e. &quot;404: There is no user with ID 123456 in the system&quot;, then the user ID should be extracted into the error response body, so that it can be provided correctly to the user in the user&#x27;s language.<p>b) Pagination is the devil. The state of the server can change while the user is paginating, leading to fragile clients. Don&#x27;t paginate your API. If you think you have a need to paginate, have one API call return a list of IDs, and have a separate API call return a list of resources for a given list of IDs, where the second API call accepts some maximum number of IDs as a query parameter. This ensures consistency from one API call to the next.

A few things I see rarely discussed that I often do:<p>- Always use a response envelope<p>- HTTP status is not the same as your application status. I always include a &quot;status&quot; field in the response envelope (OP recommends standardizing errors but I think standardize all of it)<p>- Always have an unique error code for every error your API can return (they should also be URL safe (&quot;some-thing-went-wrong&quot;), basically an enum of these should exist somewhere, the more specific the better.<p>- Offer OpenAPI whenever you can.<p>- There is no such thing as a publicly exposed &quot;private&quot; API. If it can be hit (and is not protected), it eventually will be.<p>- Do blackbox testing of your API, E2E tests are the most important kind of test you could have.<p>- (controversial) build in special test&#x2F;debug endpoints -- these help with blackbox testing.

Google published a similar recommendations: <a href="https:&#x2F;&#x2F;google.aip.dev&#x2F;" rel="nofollow">https:&#x2F;&#x2F;google.aip.dev&#x2F;</a>

&gt; 5xx for internal errors (these should be avoided at all costs)<p>An anti pattern I’ve often seen has devs avoiding 5xx errors in bizarre ways. I would change the above to make to have monitoring in place to address 5xx errors. By all means, let your code throw a 500 if things go off the rails.

&gt; 14. Use pagination<p>Generally agree with everything else but strongly disagree with pagination envelopes and offset pagination. Allow keyset pagination using ordering and limiting query parameters.

It’s a good posting. I do many of these things, but not all.<p>I’ve been designing SDKs for a long time; APIs, for a somewhat shorter time.<p>I don’t like “pure” RESTful APIs, because I feel as if they are “human-hostile.” I tend to follow the patterns set by companies like Google, where the stimulus is a fairly straightforward URI (with parameters, as opposed to a block of XML or JSON —if possible, as I know that we often still need to send big data as transaction data, which can be a pain, depending on the method), and the response is a block of structured data. That also makes it a lot easier for API clients to build requests, and allows the server to “genericize” the processing of requests.<p><i>&gt; 10. Use standardized error responses</i><p>Is something I do, along with a text header payload, describing internal information about the error. It is my experience that this text payload is never transferred, and I am forced to send a text response via the body, if I want to know internal information. That can be a pain, as it often breaks the transaction, so I have to play with the server and client, frequently, using a cloned server instance.<p>I should note that my forte is not backend development, so the chances are good that I am not familiar with all the tools at my disposal.

I’m gonna say it:<p>Many rest apis are lazy and developer friendly, not consumer friendly.<p>If you have related resources, let’s say, product and product options as two distinct endpoints:<p>- &#x2F;api&#x2F;product<p>- &#x2F;api&#x2F;options<p>Then, and I want to be clear here, it is <i>impossible</i> for a client to perform an atomic operation on multiple distinct objects types.<p>Let’s say the client needs to add a product with a single option or fail.<p>You can create a product.<p>You can create an option.<p>You can add an option to a product.<p>…but, at some point in time, a product will exist with no options on it.<p>This kind of “pure” rest api is simply convenient to the <i>developer</i> because they push the problem of object consistency to the client.<p>…but that’s not a client concern.<p>If a product needs to be associated with an option on creation, then your api should offer that as an endpoint.<p>It doesn’t meet the “standard” for a rest api?<p>Too bad.<p>Write APIs that do what the customer &#x2F; consumer needs <i>not</i> lazy APIs that just make your life easier.<p>I’ve worked with a lot of APIs and you know what I do not give the tiniest moment of care about?<p>Consistency.<p>I do. Not. Care. If POST &#x2F;api&#x2F;foo creates an object, or if the endpoint is &#x2F;api&#x2F;foo&#x2F;create.<p>Messy? Inconsistent?<p>I don’t care. Just put it in the documentation and I’ll find it and use it.<p>…but if your api forces object relational consistency onto me as an api consumer, you have no <i>idea</i> how much pain and hassle you’ve caused me having to implement my own set of fake transactions over your stupid api.<p>Please, write APIs for consumers, not according to “the rules” of rest APIs.<p>…and provide documentation. :)

ISO 8601 is bad, use RFC 3339.<p>A lot of implementation are actually based on an ISO draft which changed in final release. But most dev do not have access to the spec. For example, timezone can only be specified as offset in the standard, while implementations accept name.<p>Globally avoid ISO for software, it is non free crap.<p>Also, do not use those standard for dates with timezone in the future. Use wall time&#x2F;date and location. As timezone can change way more often than you think.

While I agree with the most aspects of this very good blog post, there is a minor detail that I would like to note:<p>While pagination is important, there is another possibility of pure size - it is using cursors, like mentioned in the JSONAPI specification[1] (containing many of the hints in the topics&#x27; post) and in this blog post[1]<p>[1] <a href="https:&#x2F;&#x2F;jsonapi.org&#x2F;format&#x2F;#fetching-pagination" rel="nofollow">https:&#x2F;&#x2F;jsonapi.org&#x2F;format&#x2F;#fetching-pagination</a><p>[2] <a href="https:&#x2F;&#x2F;dev.to&#x2F;jackmarchant&#x2F;offset-and-cursor-pagination-explained-b89" rel="nofollow">https:&#x2F;&#x2F;dev.to&#x2F;jackmarchant&#x2F;offset-and-cursor-pagination-exp...</a>

I agree with most things.<p>I really hate when APIs use different api-key headers depending on the role of the consumer.<p>It is very annoying when you get dates that are not in the ISO format. There are reasons to not use UTC everywhere. One should make that decision.<p>The reason why many APIs use POST instead of DELETE is that POST is said to be more secure.<p>Many APIs that I use do not have neither of PATCH, PUT or DELETE. An order for instance will have an order status resource that one just keeps adding status entities to. In general, well-designed systems minimize the need for changing data.

&gt; 6. Accept API key authentication ... using a custom HTTP header (such as Api-Key).<p>Wouldn&#x27;t a bearer token [1] make more sense? Defined for use by OAuth2, but I don&#x27;t see why it couldn&#x27;t be the general mechanism for... bearer tokens.<p>&gt; 11. Return created resources upon POST<p>Especially important if your database+caching layers use eventual consistency.<p>[1] <a href="https:&#x2F;&#x2F;datatracker.ietf.org&#x2F;doc&#x2F;html&#x2F;rfc6750" rel="nofollow">https:&#x2F;&#x2F;datatracker.ietf.org&#x2F;doc&#x2F;html&#x2F;rfc6750</a>

A good resource, some others I consult with<p><a href="https:&#x2F;&#x2F;cloud.google.com&#x2F;apis&#x2F;design" rel="nofollow">https:&#x2F;&#x2F;cloud.google.com&#x2F;apis&#x2F;design</a><p><a href="https:&#x2F;&#x2F;opensource.zalando.com&#x2F;restful-api-guidelines&#x2F;" rel="nofollow">https:&#x2F;&#x2F;opensource.zalando.com&#x2F;restful-api-guidelines&#x2F;</a>

Do you guys use plural or singular terms in your API endpoints or both?<p><pre><code> &#x2F;books &#x2F;books&#x2F;:id &#x2F;book &#x2F;book&#x2F;:id </code></pre> It gets harder to keep consistent when there are a lot of nouns that have the same singular&#x2F;plural form like &quot;clothing&quot;

<a href="https:&#x2F;&#x2F;www.vinaysahni.com&#x2F;best-practices-for-a-pragmatic-restful-api" rel="nofollow">https:&#x2F;&#x2F;www.vinaysahni.com&#x2F;best-practices-for-a-pragmatic-re...</a><p>Helped me get started with API design in my early career. Learning from other existing APIs helps too. such as stripe, github, shopify. Any others?<p>Something that We do at my current job:<p>* set a standard and stick with it. tweak it if needed. we even have naming standard on some of the json key. for example, use XXX_count for counting. when it doesn&#x27;t make sense, use total_XXX.<p>* Document your API, we use postman and code review API changes too.

Extra points: document the API &#x2F; have an API technical writer in the team.<p>Part of a good API design is documenting it. If you use an API specification format, such as OpenAPI, design and documentation overlap nicely.

We don&#x27;t use PATCH but use a PUT for partial objects. We have validator code at every endpoint and we validate both creates and updates. When a PUT comes in, the validator knows what can and can&#x27;t be changed. Depending on your role, the validator lets you change certain things can be updated as well. A PATCH would need these too and now you have more code to deal with. Also, it requires the developer to now worry that they have all the fields for a complete object or not.

Something I wonder is how to design search&#x2F;list endpoints where the query can be long (a list of IDs, ex: &#x2F;users?ids=123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174001,123e4567-e89b-12d3-a456-426614174002,...), so long that it can exceed the url max length (2048), after 50 UUIDs, you can quickly exceed that length, so GET is not ideal, so which method, SEARCH with a body? POST with a body?

Why would one prefer ISO 8601 dates over POSIX timestamps?

My recommendation: Use PUT everywhere instead of POST. PUT has to be idempotent, so if the request fails, the client can simply post it again. This solves issue like worrying about creating a second copy of an item if a POST timed out.<p>Using PUT to create elements means that the client has to supply the ID, but this is easily solved by using GUIDs as IDs. Most languages have a package for create a unique GUIDs.

Please don’t specify ISO8601 as the date format. That standard embodies dozens of formats. Use one specific format instead like RFC3339.

For #2, better yet, prefer RFC 3339.

A good checklist of things to mind when designing APIs. Sometimes you forget the good things.

For those in Security Theatre of HTTP APIs, I found this also useful:<p><a href="https:&#x2F;&#x2F;github.com&#x2F;yosriady&#x2F;api-development-tools" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;yosriady&#x2F;api-development-tools</a>

Reading this makes me feel like a take all the magic GraphQL does for granted

The PUT vs PATCH is debatable in different levels. One simple issue is how to resolve complex merges in a PATCH. For example if we patch a key that contains a list, what will be the expected result?

For a second there I thought this was about <i>non-web</i> APIs: <a href="https:&#x2F;&#x2F;caseymuratori.com&#x2F;blog_0024" rel="nofollow">https:&#x2F;&#x2F;caseymuratori.com&#x2F;blog_0024</a>

Hey friends! Author (@rbluethl) here. :) I just randomly noticed that my post made it to the front page! Thank you all for your comments.

lol this could have been a single line blog post: “Do whatever stripe does with their APIs.”<p>I kid. There’s some good stuff in here.

To resurface the debate, is including related endpoint urls pre-filled in a “misc” field a good idea?

The author has a poor understanding of HTTP and adjacent standards. I find it is so insufficient that he should not dispense advice yet, he must learn much more, especially about the essential yet completely unmentioned parts of a Web system: media types, hyperlinks, Link relations, cacheability. Critique:<p>2. ISO 8601 is a shit show of a standard. Last time I surveyed, there was not a single compliant implementation in the world. Recommend &quot;Date and Time on the Internet: Timestamps&quot; &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc3339" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc3339</a>&gt; instead. This standard is public&#x2F;not encumbered by stupid copy fees and is restricted to a much more reasonable profile that can actually be implemented fully and in an interoperable fashion.<p>4. Use `OPTIONS <i>` instead. &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7231#section-4.3.7" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7231#section-4.3.7</a>&gt;<p>5. This goes against the design of the Web. Do not version URIs. If the representation changes and is not backward compatible, change the media type instead, e.g. by adding a profile &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc6906" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc6906</a>&gt;. You can serve multiple representations on the same URI and vary on the request headers (e.g. Accept-</i>).<p>6. HTTP already contains a customisable mechanism. Use the standard header &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7235#section-4.2" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7235#section-4.2</a>&gt;, not the custom header `Api-Key` which is not interoperable.<p>7. &quot;Don&#x27;t use too many [HTTP status codes]&quot;: why? This opinion is not backed up with an explanation. The correct advice is: use as many status codes as arise from the requirements. `422 Unprocessable Entity` is useful in nearly every Web system.<p>8. What does &quot;reasonable&quot; mean? This lacks an explanation.<p>10. Use application&#x2F;problem+json &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7807" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7807</a>&gt; instead.<p>11. &quot;It&#x27;s a good idea to return the created resource after creating it with a POST request&quot;: why? This opinion is not backed up with an explanation. If you follow this advice, the user agent cannot programmatically distinguish between a representation reporting on the requested action&#x27;s status, and the representation of the newly created resource itself. Use the Content-Location header &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7231#section-3.1.4.2" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7231#section-3.1.4.2</a>&gt; to make that possible, use the Prefer header &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7240" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7240</a>&gt; to give the user agent some control over which representation to respond with.<p>12. &quot;Prefer PATCH over PUT&quot;: disagree, ideally you offer both since there is a trade-off involved here. The downsides of PATCH are not mentioned: the method is not (required to be) idempotent meaning it becomes moderately tricky to keep track of state, and the client is required to implement some diff operation according to the semantics of the accepted media type in the Accept-Patch header which can be difficult to get right.<p>13. Missed opportunity to advertise the OPTIONS method and related Accept-Post &lt;<a href="https:&#x2F;&#x2F;datatracker.ietf.org&#x2F;doc&#x2F;html&#x2F;draft-wilde-accept-post" rel="nofollow">https:&#x2F;&#x2F;datatracker.ietf.org&#x2F;doc&#x2F;html&#x2F;draft-wilde-accept-pos...</a>&gt; &#x2F; Accept-Patch &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc5789#section-3.1" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc5789#section-3.1</a>&gt; headers. A representation of a specific media type can self describe with the &quot;type&quot; Link relation &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc6903.html#section-6" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc6903.html#section-6</a>&gt;.<p>14. Don&#x27;t mix data with metadata. Use the Range header &lt;<a href="http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7233" rel="nofollow">http:&#x2F;&#x2F;rfc-editor.org&#x2F;rfc&#x2F;rfc7233</a>&gt; and next&#x2F;prev Link relations &lt;<a href="https:&#x2F;&#x2F;webconcepts.info&#x2F;concepts&#x2F;link-relation&#x2F;next" rel="nofollow">https:&#x2F;&#x2F;webconcepts.info&#x2F;concepts&#x2F;link-relation&#x2F;next</a>&gt; instead.<p>15. Instead of complicating both server and client, the better idea is to simply link to related resources. We are not in the 1990s any more. A well written Web server offers HTTP persistent connections, HTTP pipelining, all of which make round-trips cheap or in the case of HTTP&#x2F;2 server push, even unnecessary. Benchmark this.<p>1. + 9. betrays a weird obsession with naming. The advice is <i>not wrong</i>, but it shifts attention away from the genuinely useful areas that benefit much more from a careful design: the media types, the hyperlinks between and other hypermedia mechanisms for traversing resources (forms, URI templates). If an inexperienced programmer follows the advice from the article, he will the idea to spend lots of time mapping out resources in the identifier space and methods and possible responses for documentation purposes. This is both a waste of time because the single entry point is enough and the rest of the resources can be reached by querying the server via OPTIONS and traversing hyperlinks etc., and dangerously brittle because of strong coupling between the server and the client.

Mostly common-sense things, but I can&#x27;t wait for the community to stop trying to use PUT, PATCH, DELETE and the like. There&#x27;s a reason that in 2022 web forms only support GET and POST (and implicitly, HEAD).