How to (and how not to) design REST APIs 

I can kind of see the use case, of sending a diffrent code than 404. As a User i am Usually correlating a 404 with "typo in url" or " bad url". If your server is unavailable, there is a high chance, that you will get a 404 by a proxy. To differenciate the best practise should be "always return a body with usable in formation on 404" to make error handling easier :)

Nevermind, this is somewhat covered by #10

Then you can provide it with a key like "other_api_id". E.g. "stripe_id" if your client is going to also use the stripe API or something.

...but than.. 7:35 use prefixes? why prefixes when you just said IDs don't matter to the client. This conflicts with Rule #9

Agree 100%. People just don't take advantage of the more obscure response codes. This makes it easier for front-end consumers to react to API errors from a semantic perspective.

​@@gosnookyissue is that http status codes often doesn't fit with the application domain. It's better in my opinion to use the most common http statuses, and then have some application specific codes or handling for the rest

Glad you enjoy it!

Yup here it is: ru-vid.com/video/%D0%B2%D0%B8%D0%B4%D0%B5%D0%BE-Bxf_HMs7SeQ.html

Infra shouldn't be giving 404s, that's what 502/503/etc are for

@@adambickford8720 True, but in many environments it happens nonetheless. For example, a misconfigured nginx will return 404 if it does not know what to do with your request. The same happens if an application completely failed to start up or is currently undeployed in a Tomcat or application server and its context path is thus unknown to the server; usually it'll respond with 404 then as well.

@@jenswurm Then you should fix the root cause, not tweak everyone affected by it.

​@@adambickford8720 That root cause is partially written into the HTTP spec, RFC7231 Quote: _"The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent;"_ So a 404 can occur only temporarily and for multiple reasons, such as an authorization problem (server unwilling to disclose that the resource exists). That's not going to change anytime soon. Things like nginxes returning 404 where 502 would have been better still also is technically compliant with that spec. That misconfigured nginx genuinely has no representation of the requested resource, so 404 isn't wrong there. But let's assume that it may get fixed/improved in a couple of years. What to do until then?

REST is a description of the architecture used to design the world wide web. If REST had never happened, then websites wouldnt be able to interlink and browers wouldn't be able to render arbitrary pages. REST is a description of first and foremost hypermedia, well-defined content types, caching and content negotiation

That's an interesting point. I've never thought about it that way.

@@HrHaakon you can put a version number also in a header of the request. The important thing is, that your API is good documented.

I try really hard to avoid RPC type APIs. I find my APIs are easier to use if I somehow convert that RPC into a resource that is requested. It just makes it easier to think about.

I think that is the issue with everything software related. Technically the computer doesnt care what the URI looks like. The HATEOAS/hypermedia approach is the technical design for building autonomous systems that can adapt to topological changes without needing rewritten. The neatness of URIs is a purely human concern and where people feel the need to bike shed. I think the gist of the rules is that focus on the stuff that makes the system work first and foremost. Then be pragmatic about everything else because it is mostly subjective and will change based on who is on the team and what their current perspective on the system design is

Directly linking is problematic. It often forces you traverse via some input/home URI. The more "entry points" you add can lose the ability to evolve them.

in the theory you have a starting URL, where you get all the urls for all the resources your service provide. I do not like this at all. We have things like open api, swagger or what ever. So there is in my opinion no need for this huge overhead. But that's only my opinion on this.

It's not just in theory. How does the browser work when you open it up? You have a starting url and the returned HTML contains links that allow the browser to navigate you all over the web. The original intent was that when you have well defined content types (like HTML) then any client that understands the content schema can autonomously navigate your system state. To me the big problem is that people get stuck on JSON being their content type rather than defining more specialised content types specific to their system. Or working within their industry to define a more standards based content type to help promote interoperability.

This is basically what I did in our last big project. I put pagination details into custom X-Something headers. The body is meant for the actual requested data, metadata should always be in the headers imho.

This right here. We used to do 404s but, they honestly caused more problems. Mainly in monitoring. Is it a null resource or is it a poorly constructed URI. Also, on the client end when consuming these, usually the code that cares about the business reason of "this thing doesn't exist" has all the HTTP logic abstracted away. So parsing headers response codes becomes messy. Where is it I return an empty response with a 200. All I do is a simple null check. Now if you have a sophisticated client library that handles stuff like that, then all good. But it felt like a lot of work to go through just to make HTTP standard codes be happy. But at the end of the day, it's about being pragmatic and setting appropriate expectations. For a public API, maybe we would do a 404 because that's what most consumers expect?

I'd say there are at least 3 different levels on which absence of sth might result in 404: 1. There is an endpoint, but supplied id wasn't found in db 2. There is no such endpoint so your framework returned 404 3. The app is down, so the server returned 404

@@qj0n Yes, but there is no concept of "endpoint" in HTTP. If endpoints exist they are an internal thing about how the server is built. The client doesn't need to know the distinction between one endpoint and another, especially if they are not constructing URIs. The client also doesn't need to know whether or not you have a database. As far as the client is concerned if they're just doing GET requests for orders your server could just be an S3 bucket or a simple web server with some JSON files that hold order details arranged systematically on disk inside the webroot.

@@barneylaurance1865 ok, so let me rephrase what I wrote: 404 might mean technical server error (should be 5xx, but I think some servers like IIS return 404 when no binding on some url), no particular resource or no particular resource type. Which makes troubleshooting a bit complicated

Just be consistent at yourself first.

There is something wrong with post to get something: you lose the copyable link to browser

@@BosonCollider I see, a get also does not work usually for me as i need to provide a bearer in the header to authenticate i test api's with postman or directly from rider http tools

It's wrong to use post or put for retrieving data. There's nothing good about it please.

​​​@@jeroen7362Your client should not determine how you design your API. You will change your API when you are not using Postman? Silly reason for using post or put for retrieving Change your client if it's getting in the way. Not your API.

@@awmy3109 well i my view transport should have nothing to do with your functionality. a post and a get are just a means of transport. if a post makes sense because you have a payload in a body. that payload can contains filters and sorting parameters or an array of codes you are requesting for. So if that is what i need to send over to query data, i have to use a post, and there is nothing wrong with that. only rest purists have a problem with this.

You see and use HATEOAS every single day while viewing pages, clicking on links, and thereby driving the next application state.

@@edwardevlogiev4087 Bla bla bla... In a world of open api, swagger or whatever, HATEOAS is a relic from the past. Clunky and too much noise for a simple api. See, how opinions are different?

@@RealDieselMeister You have no idea if I agree or disagree with the video, but still are arguing with my "opinion". I'm commenting that @adambickford8720 sees HATEOAS being used every single day (irl, as he put it), no that he uses it or must use it.

You are both correct. HATEOAS is not a relic from the past. It is literally what the web uses to navigate between pages. Your main argument is that it isnt applicable to the systems you work on. So dont use it. Push back against the manager/marketing nonsense that everything is REST. Because it isnt

You did get the wrong URL. You thought you had a URL of an order, but there's no order at that URL, therefore you got the wrong URL.

@@barneylaurance1865 so how would i decide whether that's an expected error or a system error? Maybe the service is just down. Seems like a way to confuse your api consumers.

I've said in another video, I wish best practices were called "maybe something you should think about when X, Y, Z and here are the trade-offs". 😂

That's was my point in various aspects of the video, the whole industry can be wrong. And a lot of the other "rules" were to just follow the industry, but in this case, they chose not to. I agree I didn't give my opnion much on this one heavily, but it relates to what you define as a resource. If a resource isn't found then it's a 404. What's a resource? Whatever you want it to be. If you decide that your resource represents a database record because it has path segments as IDs, then sure, so be it. In my other example with having the idempotent ID in the URI, that's a very unique resource.

> do not use the errors of that transport in your code for functional meaning Taking this to an extreme, a 500 should be a 200. The transport made it to the server & then back, ergo 200. I do disagree, I've had some people try to impress on me very strongly that the HTTP result code *should* very much map to the application result. I do agree that bad-args should be a 400. I think in this comment I was going to see a suggestion to not use 410 but instead 400 for bad user args. Further, having 400 vs 404 vs 500 in logs is really great. Seeing a surge in 400s where none are expected can be a good indicator. I do agree that someone manually trying URLs should not be able to overly pollute logs nor trigger any meaningful alarms (unless they are actively degrading the service, or perhaps a 'security' alarm, but no log-scan type of alarms should be triggered by someone trying a bad URL half a dozen times)

@@SeaBike007 Well those people were impressing strongly on me too but i see no argument for it, for REST it was just convenient to overload errorcodes and give them more then one use. It does not make it a good idea. A 500 needs to be in the log when your api is crashing badly, a 500 because of some strange user input that does not make sense needs no 500 because all transport and api's works perfectly. just return a functional errormessage with status 200 and in it something like succes=false, message=can not devide by 0. A 404 401 etc should only show up when an api can not be found or access denied when that is not expected, so a hacker is unexpected and should show up in the error logs for shure! when there is a lot of hacking and fishing going on you need to take counter measures. But i do understand that what i am basically saying is that REST is a bad practice in "my book" I focus on maintainabillity (only real problems in a log, every exception like a 404 500 is unexpected and needs follow up.) and functionality. I have much more functional errors that need to be dealth with then just the few http errorcodes. So i state that those errorcodes are meant for the transport and not for application logic. Wen you switch from http to a message bus you do not get 404 on the transport. why should your code need to be dependend on the transport errorcodes?

@@jeroen7362 Returning 2XX status codes for a failure (either of the client or the server) is literally the worst thing you can make as an API developer. You're arguing with polluting the logs, but that is a non issue if your API is designed properly, since you can hapilly ignore 4XX codes, as those are user errors. "A 404 401 etc should only show up when an api can not be found or access denied when that is not expected" - those are exactly uses cases for 5XX status codes, lol. You know basically nothing about HTTP standard as far as I can see and with each "point" you're trying to make, the more it is visible.

@@MarekFr Well i see you try to make a point but without any argument. You only speak of what is told to you without thinking if it makes sense or not. If you have a good argument why it is a good idea to overload errorcodes of a transport to mean more then one thing let me know the actual argument to do that. Also you are wrong about the errors itself if you would use them. a 5xx is really not intended for not found 404, not authenticated 401, or not authorized 403. Ff an api is not found you are not in charge of the errocodes, the transport will throw it for you. Read the docs again and lol at your own reaction. http 404 means that there was nothing at that url (resource not found) it means the api is simply not deployed anymore at that adress, or it is there but the dns is not pointing to that host. or the api client is configured with a wrong url. when i see that in my log files (azure insights is what i work with) i know something is wrong, why would a 404 happen if all is expected to function without problems? So i have to find out and fix it. Now all you resties are overloading the 404 and use it when a book is not found by the api. Who cares? i do not want to see those errors in the log, it is not an exception for the transport, everything works! the book was just not found, that is a functional error not a technical transport error and therefore it should not raise red flags. a 500 and 503 etc is a real red flag it could only show up if your api is down or failing, it somehow did not handle its exceptions internally and fails badly. if to many 500 show up it will even trigger Rapid Fail protection in iis and reboot the whole api. Yes you do your thing as you like, but i know my stuff.

@@jeroen7362 What do you mean transport? Transport layer is TCP, HTTP is application layer. If a server is not found, your request will timeout or throw DNS error, not 404. You should really read HTTP standard before you make any arguments which don't even make sense.

If that's what everyone is using in an industry where we can't standardize almost nothing above the transport layer then YES, oh hell YES!

This video specifically or others have the same issue for you?

@@CodeOpinion This is your first video I stumbled on so I don't have other observations. I didn't mean to make it negative, I was just frustrated that I couldn't understand some of the points you were making. It's possible that my confusion stems from lack of experience, maybe other viewers didn't have this issue but for me it was difficult to follow. Maybe I would have been able to connect the dots if I had more experience but I think everyone would appreciate it if you spoke in a more structured and straightforward way. For example, you mentioned hypermedia a few times. I don't understand how it relates to the topic. I suppose you don't mean hypermedia as in audio and video but something else.

Some systems have security requirements where they are not allowed to leak information like the ordering of items, and size of collections, and relative timings of creation of items. And auto increment ids will leak all these things. The fix is to either use some large random id or to encrypt ids before providing to clients. Both will be string ids then.

@@Sammi84Interesting point. if my 'id' field is classified - I would omit it from the api, and have a dedicated 'key' or 'code' field for the unique identifier I expose to the api users. Similarly, I omit 'password' field in my 'Auth' entity (which represents a user login registered in the system).

@@gordondaniel I agree 100%. Omit the filed, hash the field, or use a non-detail leaking generated code. Either way, your api will know how to translate it back to a useful value.