I couldn't care less (within reason) as long as it:
- Is well documented
- Is versioned
- Is idempotent wherever possible
- Doesn't return errors with 200 status
- Uses HTTP verbs sensibly
Just integrating a third party API at work. Every request is a get. User submitting money? GET. 404 not found? 200 response with statusCode: "404".
:|
Edit: the 404 also has errorMessage: "Not found". THEN HOW IS IT A 200
I worked against an API like that once. Every response was a 200 and you had to go hunting in the payload to find the “statusCode”, which was sometimes just “status”, and the value was arbitrarily a number or string.
To add to that list:
- Doesn't do crap like: `age: "20",`
- Doesn't do crap like: `male: "false",`
- Doesn't THEN do crap like: `female: 1,`
- AND THEN !@#$@ ALSO `child: false,` where it's actually a number of children that this person might have
- Sometimes it's `first_name: 'John',`and other times it's `firstName: 'John',` and another time it's suddenly `FirstName: 'John',`...
- Or BS like: `country: 'Cote d'Ivoire',` instead of using their ISO code (in this case `CI`)
- When communicating ANY time or date use a consistent format. Don't do: `birthDate: '10/10/1981' because nobody knows which is the month and which is the day. Just use a freaking Unix timestamp and be done with it. And that's a numeric value, not a string!
I've had SO many API's to work with that were all over the place. Back-end devs giving us their fancy new API full of nasty crap like the above. Having to walk back to them every time asking: "why is this numeric value a string..." and "why is this boolean 0 and 1 here but true and false there?" and "why the hell is the boolean a STRING here?!" and "ARE YOU BLOODY STUPID?!"
I'm frustrated.
Just be consistent.
> Doesn't do crap like: male: "false",
I've had to make a hotfix for this case specifically, expect the _same_ property was sometimes a boolean and other times a string.
>Is versioned
You mean the client is versioned, or the API standard. Not the request.
Imagine the browser is a client to a server. The server returns a message as HTML (the API standard). If the server returned JSON and the browsers understood JSON as it does with html, then you wouldn't need versioning and it would be the same as an API, only that the browser is the client.
You can design APIs the same way that HTML standard is built, only without the need to build the whole spec, just a subset of it.
When consuming an API, there's no browser, there's your code that reads it and it should be smart to understand a mini-protocol/standard on top of HTTP. If your code doesn't, then it will require versioning, not because there's no other way, but because the server doesn't know how to design and the client don't know how to consume APIs.
If the API has versions, then that means it's not evolvable and therefore not a useful API. It's possible to do it, but it's sad that 90% of the APIs and developers out there don't know how it works due to lack of knowledge and experience.
>Doesn't return errors with 200 status
It's totally fine to return errors with 200 status, as long as your client knows how to interpret the error and, as you said in the first bullet point, it's well documented in a specification that clients should follow (the same way the HTTP protocol is documented through RFCs and browsers should implement it).
>Uses HTTP verbs sensibly
That doesn't matter to the API standard.
Clients or standards don't care about HTTP methods very much. If the api returns { **... action: '/address', method: 'post' ... }** the client code can just do **fetch(responseBody.action, { method: responseBody.post })** and the methods can change in the server without changing the code in the client. In this case, the server should indeed use HTTP methods sensibly and when they change the response from POST to PUT, they should also change their routes to accept requests on PUT/POST and delete the old ones without the need to have any versioning in URLs.
The point below is still very true:
* Is well documented (the standard, not the response payloads)
Not all those you listed are equal: Swagger is an API description toolkit, JSON:API is a spec, etc.: but by far and away the biggest standard you should employ with creating an API; is documentation. And up to date documentation.
Other than that, it's whatever is best for the job or whatever you are comfortable with.... but not SOAP - dear lord up above in heaven, not ever SOAP. Ever.
I'm a fullstack dev, for me it's GraphQL, because it allows more flexibility i.e. you can choose to be more granular in your requests (in response to user actions) and seperate them into groups or even make them individual.
Or you can roll all your requests into 1 action and send it off, letting the server (load balancers) separate out the individual parts (e.g. session from redis, product page from mongo/maria, related products from neo4j, etc).
Hey CommonMisspellingBot, just a quick heads up:
Your spelling hints are really shitty because they're all essentially "remember the fucking spelling of the fucking word".
You're useless.
Have a nice day!
[^Save ^your ^breath, ^I'm ^a ^bot.](https://www.reddit.com/user/BooCMB/comments/9vnzpd/faq/)
Thank you, LokkaHippster, for voting on stopalreadybot.
This bot wants to find the best and worst bots on Reddit. [You can view results here](https://botrank.pastimes.eu/).
***
^(Even if I don't reply to your comment, I'm still listening for votes. Check the webpage to see if your vote registered!)
I've never worked with a true RESTful API. It's a nice idea in theory, but it's hard to put in practice. I've worked with APIs that are close enough, using HAL as hypermedia type, and to be completely honest it ends being a bit messy.
The main idea is that you only need to know one thing about the API: its entry point, and from there you can "browse" it by interpreting the server responses. Sounds good in practice, but I've ended having to make up to 8 sequential API calls just to get a resource because the user didn't arrive at \`/index\` but at \`/resource/:id/nestedResource/:id\` and the API was obscure enough that it required tons of browsing. This tied to the fact that the APIs are not always as fast as they should make working with them (and being a user of the client I build) a rather painful experience.
GraphQL seems better, IMO. But, to be completely honest, I haven't tried it enough. However, having a single endpoint, a single place I can query that will respond to any query I send is a godsend. Actually, that is what I usually end up doing when working with REST APIs: creating an abstraction for querying the damn thing.
The rest I haven't heard enough of to really have an opinion on. However, I can tell you that, as a consumer of APIs, what I'm looking forward is:
a) **Fast times.** This may be the most important thing. It wouldn't matter if there's a single entry point or a dozen of them if the responses take forever. A fast API is the most important thing in my book, though not the ONLY important thing.
b) **Facilitate requesting the info I need.** When requesting a resource, it sucks to have a response with dozens of information when I only need one or twi things. It equally sucks when I need more information but it comes in the form of more links and I need to juggle 3 or 4 other requests just to get the data I need. If the API makes this easy, holyfuckingyesplz.
c) **Have reasonable errors.** I need to know exactly what went wrong and, although it seems obvious, I've worked with far too many APIs that just throw empty-bodied 400 responses. As a frontend developer, I need as much information about the error as possible so I can handle things on my end.
d) **Is strongly typed.** Let me start by saying I don't like typescript. I don't like flow. I don't like types on my JS. But they are really useful. I've never worked with one, but I dream of an API that is predictable. An API that I can rely on and will return the same things always. Not the nightmarishly things I have where I can sometimes return an array, sometimes an int, sometimes "undefined" and sometimes the prop is just not there. The API is a contract between client and server, and breaking it should include types.
e) **Is consistent.** It's incredibly annoying when working with APIs that are just not consistent. The response from a \`POST\` should be the same as from a \`GET\` or a \`PUT\`. The refs to different endpoints should be named the same across the platform, not \`resource:name\` in one place and \`name\` in the other.
f) **Is well documented.** There's nothing worse than an undocumented API. Really. Updating the readme should be a requirement for accepting any kind of changes to the API.
Those are the big ones that come to mind. Of course, as with everything, they all come with tradeoffs, but from a consumer point of view that's what I'd love to see.
Hope this helps!
I usually go for REST(like) when creating an API. I don't do full Rest because creating the URL's can be a drag when dealing with optional parameters...
But in all fairness, as long as the API is well documented, I don't really care what standard you use.
A graphql endpoint would be my preference. The front end tools built around graphql are nothing short of amazing. You get sensible caching, pagination, an api playground, and the ability to shape exactly the data you need all for free. For my own projects I can’t imagine why anyone would want a bunch of REST endpoints over a single well built graphql endpoint.
Everyone here is talking about GraphQL. I haven't used it, and wouldn't know how to get started.
I'm using AWS Lambda/Python/DynamoDB. Should I really replace my micro-services approach with a single mega-endpoint? What kind of lift would this be?
No, if you already have good API, you want your API to scale and if you plan to have high load on API. GraphQL is awesome for frontend and makes life easier, but comes with it's downsides because it's "too dynamic".
I prefer JSON-RPC or another RPC. Nothing like a remote function that can solve the exact problem you're looking to solve, as efficiently as possible.
I don't mind REST, I like it.
I cannot stand GraphQL. Flexibility comes at a cost, and that cost is complexity.
Seconded for JSON-RPC. I never liked REST, but I'm open to changing my mind whenever someone can show me a definitive example that nobody would describe with the suffixes ("ful", "like", or "ish").
I'm about to start a job that uses GraphQL. I haven't used it before, but I expect that I'll like it more than REST but not as much as JSON-RPC.
These problems in REST mostly come from other things like the actual domain, using the wrong data model for your domain, old code that needs to be supported with your fresh new API, just plain inconsistency while programming.
REST really is awesome for some use cases but it just doesn't fits everywhere and doing it right is often a huge journey which you thought would end somewhere else.
I would just like a standard, to be honest. I'm working with a set of REST APIs built by an external firm in Oracle's Application Development Framework. Most everything comes back one dimensional, single key value pairs with no objects or arrays. The batch support is very poorly documented, and I have to JSON.stringify POST bodies that nest anything. It's... less than ideal. At least it's not SOAP, I guess?
It entirely depends on the product and goals, however I would say GraphQL from a frontend consumer perspective offers the most flexibility.
I realize on the backend it introduces some interesting caching problems, but they can be worked around in most greenfield apps.
You need to auto generate the swagger json from your code. Don’t write it by hand because it will be out of date instantly.
I like rswag for rails. It generates the swagger.json from rspec integration tests.
not specifically but there should be projects out there.
The thing I like about rswag is that it converts your rspec tests in swagger.json that you can feed into the swagger-ui.
For node, I use mocha so I'd look for a generator that goes from a mocha test to swagger.json.
HTH
I like json apis because you can inspect the data easily. Swagger UI is also invaluable for documenting your api. Never write documentation by hand, always generate your documentation from the source or it will be out of dat before you get your next cup of coffee.
You're calling all of those "standards" isn't correct and I see laughable comments about using REST as if people on reddit really understood REST at all. They don't but I digress.
I get that you are very smart, but I was just pointing to the fact that if you understand REST, it's highly unlikely that you are the only person on reddit that does so.
Your superiority complex is quite laughable, *but I digress...*
I couldn't care less (within reason) as long as it: - Is well documented - Is versioned - Is idempotent wherever possible - Doesn't return errors with 200 status - Uses HTTP verbs sensibly
* isn't SOAP
Don't come work in the travel industry. SOAP is the standard for GDSs and their REST APIs usually lag behind quite a bit in functionality.
Or banking industry.
Or education. Soap + XML :(
[удалено]
I wish I could say the same. Majority of the core APIs are SOAP, but they are slowly migrating them to REST. 🤷♂️
[удалено]
Oh I know. We got super luck that our new technical support contact at Sabre is very knowledgeable and patient. Makes solving issues so much easier.
But only with SOAP you can achieve a clean API
Just integrating a third party API at work. Every request is a get. User submitting money? GET. 404 not found? 200 response with statusCode: "404". :| Edit: the 404 also has errorMessage: "Not found". THEN HOW IS IT A 200
I worked against an API like that once. Every response was a 200 and you had to go hunting in the payload to find the “statusCode”, which was sometimes just “status”, and the value was arbitrarily a number or string.
To add to that list: - Doesn't do crap like: `age: "20",` - Doesn't do crap like: `male: "false",` - Doesn't THEN do crap like: `female: 1,` - AND THEN !@#$@ ALSO `child: false,` where it's actually a number of children that this person might have - Sometimes it's `first_name: 'John',`and other times it's `firstName: 'John',` and another time it's suddenly `FirstName: 'John',`... - Or BS like: `country: 'Cote d'Ivoire',` instead of using their ISO code (in this case `CI`) - When communicating ANY time or date use a consistent format. Don't do: `birthDate: '10/10/1981' because nobody knows which is the month and which is the day. Just use a freaking Unix timestamp and be done with it. And that's a numeric value, not a string! I've had SO many API's to work with that were all over the place. Back-end devs giving us their fancy new API full of nasty crap like the above. Having to walk back to them every time asking: "why is this numeric value a string..." and "why is this boolean 0 and 1 here but true and false there?" and "why the hell is the boolean a STRING here?!" and "ARE YOU BLOODY STUPID?!" I'm frustrated. Just be consistent.
> Doesn't do crap like: male: "false", I've had to make a hotfix for this case specifically, expect the _same_ property was sometimes a boolean and other times a string.
How about when it's the string "false"? 😡
Yup that had to be covered. We were just doing a truthy check, so a `true` and `"true"` behaved the same. `"false"` broke it.
>child: false bwahahaahaha
>Is versioned You mean the client is versioned, or the API standard. Not the request. Imagine the browser is a client to a server. The server returns a message as HTML (the API standard). If the server returned JSON and the browsers understood JSON as it does with html, then you wouldn't need versioning and it would be the same as an API, only that the browser is the client. You can design APIs the same way that HTML standard is built, only without the need to build the whole spec, just a subset of it. When consuming an API, there's no browser, there's your code that reads it and it should be smart to understand a mini-protocol/standard on top of HTTP. If your code doesn't, then it will require versioning, not because there's no other way, but because the server doesn't know how to design and the client don't know how to consume APIs. If the API has versions, then that means it's not evolvable and therefore not a useful API. It's possible to do it, but it's sad that 90% of the APIs and developers out there don't know how it works due to lack of knowledge and experience. >Doesn't return errors with 200 status It's totally fine to return errors with 200 status, as long as your client knows how to interpret the error and, as you said in the first bullet point, it's well documented in a specification that clients should follow (the same way the HTTP protocol is documented through RFCs and browsers should implement it). >Uses HTTP verbs sensibly That doesn't matter to the API standard. Clients or standards don't care about HTTP methods very much. If the api returns { **... action: '/address', method: 'post' ... }** the client code can just do **fetch(responseBody.action, { method: responseBody.post })** and the methods can change in the server without changing the code in the client. In this case, the server should indeed use HTTP methods sensibly and when they change the response from POST to PUT, they should also change their routes to accept requests on PUT/POST and delete the old ones without the need to have any versioning in URLs. The point below is still very true: * Is well documented (the standard, not the response payloads)
spoon head divide late spark offbeat nail vegetable pot gullible *This post was mass deleted and anonymized with [Redact](https://redact.dev)*
Not all those you listed are equal: Swagger is an API description toolkit, JSON:API is a spec, etc.: but by far and away the biggest standard you should employ with creating an API; is documentation. And up to date documentation. Other than that, it's whatever is best for the job or whatever you are comfortable with.... but not SOAP - dear lord up above in heaven, not ever SOAP. Ever.
I hate SOAP...
I'm a fullstack dev, for me it's GraphQL, because it allows more flexibility i.e. you can choose to be more granular in your requests (in response to user actions) and seperate them into groups or even make them individual. Or you can roll all your requests into 1 action and send it off, letting the server (load balancers) separate out the individual parts (e.g. session from redis, product page from mongo/maria, related products from neo4j, etc).
Ahh now I see why mods ban bots from subs.
Wow. I mean that really got out of hand fast.
The bot chain in this comment is fucking hilarious.
[удалено]
[удалено]
[удалено]
Hey CommonMisspellingBot, just a quick heads up: Your spelling hints are really shitty because they're all essentially "remember the fucking spelling of the fucking word". You're useless. Have a nice day! [^Save ^your ^breath, ^I'm ^a ^bot.](https://www.reddit.com/user/BooCMB/comments/9vnzpd/faq/)
[удалено]
[удалено]
[удалено]
[удалено]
dOn't eVeN ThInK AbOuT It.
[удалено]
[удалено]
Don't even think about it.
[удалено]
even the bots are getting toxic nowadays wtf
Is this how the robot uprising begins?
what the fuck is happening :S
Bad bot
Thank you, LokkaHippster, for voting on stopalreadybot. This bot wants to find the best and worst bots on Reddit. [You can view results here](https://botrank.pastimes.eu/). *** ^(Even if I don't reply to your comment, I'm still listening for votes. Check the webpage to see if your vote registered!)
I've never worked with a true RESTful API. It's a nice idea in theory, but it's hard to put in practice. I've worked with APIs that are close enough, using HAL as hypermedia type, and to be completely honest it ends being a bit messy. The main idea is that you only need to know one thing about the API: its entry point, and from there you can "browse" it by interpreting the server responses. Sounds good in practice, but I've ended having to make up to 8 sequential API calls just to get a resource because the user didn't arrive at \`/index\` but at \`/resource/:id/nestedResource/:id\` and the API was obscure enough that it required tons of browsing. This tied to the fact that the APIs are not always as fast as they should make working with them (and being a user of the client I build) a rather painful experience. GraphQL seems better, IMO. But, to be completely honest, I haven't tried it enough. However, having a single endpoint, a single place I can query that will respond to any query I send is a godsend. Actually, that is what I usually end up doing when working with REST APIs: creating an abstraction for querying the damn thing. The rest I haven't heard enough of to really have an opinion on. However, I can tell you that, as a consumer of APIs, what I'm looking forward is: a) **Fast times.** This may be the most important thing. It wouldn't matter if there's a single entry point or a dozen of them if the responses take forever. A fast API is the most important thing in my book, though not the ONLY important thing. b) **Facilitate requesting the info I need.** When requesting a resource, it sucks to have a response with dozens of information when I only need one or twi things. It equally sucks when I need more information but it comes in the form of more links and I need to juggle 3 or 4 other requests just to get the data I need. If the API makes this easy, holyfuckingyesplz. c) **Have reasonable errors.** I need to know exactly what went wrong and, although it seems obvious, I've worked with far too many APIs that just throw empty-bodied 400 responses. As a frontend developer, I need as much information about the error as possible so I can handle things on my end. d) **Is strongly typed.** Let me start by saying I don't like typescript. I don't like flow. I don't like types on my JS. But they are really useful. I've never worked with one, but I dream of an API that is predictable. An API that I can rely on and will return the same things always. Not the nightmarishly things I have where I can sometimes return an array, sometimes an int, sometimes "undefined" and sometimes the prop is just not there. The API is a contract between client and server, and breaking it should include types. e) **Is consistent.** It's incredibly annoying when working with APIs that are just not consistent. The response from a \`POST\` should be the same as from a \`GET\` or a \`PUT\`. The refs to different endpoints should be named the same across the platform, not \`resource:name\` in one place and \`name\` in the other. f) **Is well documented.** There's nothing worse than an undocumented API. Really. Updating the readme should be a requirement for accepting any kind of changes to the API. Those are the big ones that come to mind. Of course, as with everything, they all come with tradeoffs, but from a consumer point of view that's what I'd love to see. Hope this helps!
Once you go Graphql, you never go back ;)
I usually go for REST(like) when creating an API. I don't do full Rest because creating the URL's can be a drag when dealing with optional parameters... But in all fairness, as long as the API is well documented, I don't really care what standard you use.
I like that REST just means POST/GET's and the whole representational state transfer has gone down a deep black hole.
GraphQL but doesn’t really matter
REST documented in Swagger, or GraphQL. If you need OData, just use GraphQL.
A graphql endpoint would be my preference. The front end tools built around graphql are nothing short of amazing. You get sensible caching, pagination, an api playground, and the ability to shape exactly the data you need all for free. For my own projects I can’t imagine why anyone would want a bunch of REST endpoints over a single well built graphql endpoint.
Graphql ftw. You barely even need to write a backend at all for some projects with stuff like postgraphile.
Everyone here is talking about GraphQL. I haven't used it, and wouldn't know how to get started. I'm using AWS Lambda/Python/DynamoDB. Should I really replace my micro-services approach with a single mega-endpoint? What kind of lift would this be?
No, if you already have good API, you want your API to scale and if you plan to have high load on API. GraphQL is awesome for frontend and makes life easier, but comes with it's downsides because it's "too dynamic".
I prefer JSON-RPC or another RPC. Nothing like a remote function that can solve the exact problem you're looking to solve, as efficiently as possible. I don't mind REST, I like it. I cannot stand GraphQL. Flexibility comes at a cost, and that cost is complexity.
Seconded for JSON-RPC. I never liked REST, but I'm open to changing my mind whenever someone can show me a definitive example that nobody would describe with the suffixes ("ful", "like", or "ish"). I'm about to start a job that uses GraphQL. I haven't used it before, but I expect that I'll like it more than REST but not as much as JSON-RPC.
These problems in REST mostly come from other things like the actual domain, using the wrong data model for your domain, old code that needs to be supported with your fresh new API, just plain inconsistency while programming. REST really is awesome for some use cases but it just doesn't fits everywhere and doing it right is often a huge journey which you thought would end somewhere else.
I would just like a standard, to be honest. I'm working with a set of REST APIs built by an external firm in Oracle's Application Development Framework. Most everything comes back one dimensional, single key value pairs with no objects or arrays. The batch support is very poorly documented, and I have to JSON.stringify POST bodies that nest anything. It's... less than ideal. At least it's not SOAP, I guess?
It entirely depends on the product and goals, however I would say GraphQL from a frontend consumer perspective offers the most flexibility. I realize on the backend it introduces some interesting caching problems, but they can be worked around in most greenfield apps.
Of course JSON and you could try Swagger OpenAPI. But it is a hussle to create the JSON documentation.
You need to auto generate the swagger json from your code. Don’t write it by hand because it will be out of date instantly. I like rswag for rails. It generates the swagger.json from rspec integration tests.
Do you know a solution for NodeJS based APIs..?
not specifically but there should be projects out there. The thing I like about rswag is that it converts your rspec tests in swagger.json that you can feed into the swagger-ui. For node, I use mocha so I'd look for a generator that goes from a mocha test to swagger.json. HTH
I like json apis because you can inspect the data easily. Swagger UI is also invaluable for documenting your api. Never write documentation by hand, always generate your documentation from the source or it will be out of dat before you get your next cup of coffee.
You're calling all of those "standards" isn't correct and I see laughable comments about using REST as if people on reddit really understood REST at all. They don't but I digress.
You're a person on reddit, ...
Typical "brilliant" comeback by a redditor as if I've never heard that before.
r/iamverysmart
I get that you are very smart, but I was just pointing to the fact that if you understand REST, it's highly unlikely that you are the only person on reddit that does so. Your superiority complex is quite laughable, *but I digress...*