8 ms·

I have worked with a few vendors to integrate with their API. Some things that need to be considered: 1. Do they provide an easy way to create a sandbox/stagin

I have worked with a few vendors to integrate with their API. Some things that need to be considered: 1. Do they provide an easy way to create a sandbox/staging/test/dev environment ? Good example: Stripe. Really bad example: Paypal. Why ? Well, for starters, you need to create a completely separate account just to get a sandbox env in paypal. Then there is no guarantee that sandbox is identical to production in terms of ability to build and test. 2. What are their Rate Limits ? Some APIs are well designed but have terrible rate limits. 3. Authentication mechanism and security. How do they authenticate the API access ? This can matter for building critical apps. 4. Do they use REST or not ? 5. Do they have good documentation ? Can you do a quick test using their documentation or is it required to call their support ? 6. Do they have good support ? 7. Do they version their API changes and are those changes backward compatible ? I am sure there are more but these are some good ones to start with.

mceachen 9y ago
Great list. I'd also suggest researching what portion of their mutation API is idempotent. If they highlight those endpoints, they know what they're doing. Network and system hiccups/outages cause non-trivial error rates with non-trivial load, so understanding how to recover from those errors is critical (to your ability to sleep through the night because your on-call pager stayed silent).
- guscost 9y ago
  If the documentation says it is a REST API, you could be justified in expecting all POST requests to be non-idempotent, and all other requests to be idempotent. But it would still be reassuring to see this stated explicitly!
  - bbarn 9y ago
    That's only if all calls are isolated to simply modifying state of objects, and not causing events. For example, if doing a PUT on a user to change their email kicks off an email to verify the account, then it's not idempotent in my mind.
    - heavenlyblue 9y ago
      Come on: that’s easily fixable if the provider cares: just assign an ID to every mutation operation. Never repeat the operation if called again. In the real world even bigger players such as AdWords would time out on our bulk requests to them if making >100M changes, without giving any errors back (the jobs just simply tend to disappear; or the jobs never get submitted in the first place). Truth is, you may or may not be discussing the appeal of the REST; but the issue in this context is solved already - and it’s only a matter of professionalism and therefore, the resources required to build something that just works. But in the real world we get stoned students writing the majority of the APIs; having read a few how-to’s.
      - bbarn 9y ago
        I don't disagree, the original question was how to vet an API though, and I think it's a valid thing to look for.
    - guscost 9y ago
      It could be argued this is a departure from the standard, but on the other hand allowing PUT to have side-effects might be more user-friendly than an extra POST to a special "email invitation" resource. Would you prefer to see this behavior (as long as it was documented)?
enraged_camel 9y ago
Off-topic: Regarding Stripe's sandbox, I really dislike their web GUI. After creating a bunch of test customers for instance, deleting them requires going into each and every single customer and then clicking "Delete". There is no way to multi-select and batch-delete. (Yes, it can be done programmatically, but that's not always feasible/practical, especially if I want to keep certain customer accounts alive.) Similarly, after deleting a customer, it takes you back to the customer list, but it's not always up-to-date. Sometimes the front-end can detect that updates have occurred in the list (i.e. something has been deleted) but it requires a manual refresh.
- codegeek 9y ago
  Funny but I agree with you about Stripe's dashboard GUI. They could do better.
dehrmann 9y ago
> Do they use REST or not Meh. REST semantics really only works well when you're doing CRUD operations. They get clunky when something's modeled around actions rather than entities. That said, make sure their response codes and methods make sense.
- majormajor 9y ago
  Spinning this a slightly different direction: think about what their API operation model is, and how well it lines up with your current and (more importantly) expected future use cases? If you expect that you might need to significantly change what you're doing in the future, having a more simple, composable model around resources that you can call as you need might save your ass down the line compared to if they model things as specific RPC use cases and you find yourself needing a particular variation they don't support out of the box.
- zkomp 9y ago
  I agree in the sense rest is not as imortant as say: is the api XML or JSON? I’ve integrated many B2B APIs which tend to be varying degrees of XML, plain and sane to rabbithole insane or worst of all SOAP which apparently is really still a thing people use and take seriously in B2B api context. Sigh, xml hard at work solving a problem we never seen, but creates such a bloted horrible mess where json would have been simple and better.
  - dehrmann 9y ago
    I see both sides. The magic of SOAP is you can give a tool a WSDL and it will generate bindings in a language of your choice. The downside is it has to be pretty complicated to enable the magic, so building it can be complicated, and debugging it is a nightmare. You could say the same about a lot of modern JS, and that's been somewhat solved by amazing tooling.
    - zkomp 9y ago
      Yes absolutely: this very magic is precisely what is so horrible and imho a rabbithole of insanity. It is CORBA resurrected with XML. In my data oriented mind, the primary thing that matters is the data that is sent, the second is other semantics like idempotency. Neither SOAP nor XML solve or helps: there might be no wsdl bindings in your language, or they are badly implemented (true in my experience). XML make people nest structures where it could have been flatter, SOAP even more, and annotates everything whithout a need for that. This cost for no reason but to entertain the CORBA like pipe dream, or should I say nightmare. We just resorted to pulling out data from xml with xpath. And more or less template the response back, no wsdl and very simple. But why inflict this pain on your API users?
jholman 9y ago
#4 (REST) should not be on this list. There are (at least) three senses of "REST" in use in the development world, and none of them are important in an API. The first is the original definition, laid out in Fielding's thesis. (Normally I call this "the correct definition".) This includes requiring HATEOS, which is far from a necessary property in a good API, and arguably a bad feature because it increases payload sizes. The next is the definition popularized by Rails [1]. This is never precisely outlined anywhere as far as I know, but most people seem to think it requires using URLs with particular patterns (to see an example, just do `rake routes` on any Rails project that doesn't use weird custom routing in routes.rb). Also most people seem to think it requires using PUT for overwriting updates and DELETE for deletions. All of these conventions are not-bad. But they're also not particularly good; they amount to a variable naming convention that happens to be pretty reasonable. Other systems of organization are also perfectly good! But anyway, this is not an important feature in an API. The third definition you'll see sometimes is "our API uses HTTP, therefore it's REST, we're buzzword-compliant". Fuck your buzzword compliance, no that doesn't make your API RESTful. And in some cases, these bozos can't even use HTTP correctly (for example using GETs for side-effect-ful requests). This is pretty much indefensible, but it'll still happen. So if you DO care about one of the first two definitions, don't take it on faith that someone who says "our API is RESTful" knows what that even means. Also, the first two definitions both work in terms of "representations of resources", and all three of the above apply to HTTP [2]. It's not at all clear that either of these are good features in an API. They both have the advantage that they make implementation more predictable, so that's often (usually? almost always?) a great idea. Yay! But resource-representation is a bit bloaty, and so is HTTP, so for some situations, it's more appropriate to discard either or both of those design parameters. For example, suppose you're monitoring some terrifyingly dense IoT deployment, and you want your swarm of sensors to send updates ten times a second. Differential updates over Apache Thrift (or over Google Protobuff) is certainly not over HTTP, and you have to squint pretty hard to to see the differentials as resources. (Mind you, you'd probably also want to send some checkpoints less-frequently, and you could characterize these as resources without too much difficulty.) In summary: REST means different things to different people, and there's a lot of good sense in those communities (I mean, not the third-listed liars, but the other two). BUT, probably you don't actually care about RESTfulness per se, in that cute conventional URI/path patterns are unimportant, and HATEOS is somewhere between nice-to-have and undesirable. HTH Footnote 1: I'm not claiming that authors of Rails (DHH et al) were confused about the definition of REST. As far as I can tell, when they said "make your routes RESTful", they weren't claiming that doing so necessitated using their cute method/URI convention, they were simply claiming that doing so was compatible, and that following some convention is a good idea, and here's a good convention. Yay! Well said! Unfortunately most people who wrote simplifying articles on the subject got it wrong, so now we have an industry full of semi-literates quoting non-existent scripture. Footnote 2: Strictly speaking Fielding's thesis is about what he thinks HTTP did well, and is intended to be largely advice to designers of future protocols intended to compete with HTTP. That's why so much of the "architectural style" is about stuff that's built into HTTP, such that the designer of an HTTP API cannot fuck it up. API authors are not the primary intended audience of the thesis!

mceachen 9y ago

Great list. I'd also suggest researching what portion of their mutation API is idempotent. If they highlight those endpoints, they know what they're doing. Network and system hiccups/outages cause non-trivial error rates with non-trivial load, so understanding how to recover from those errors is critical (to your ability to sleep through the night because your on-call pager stayed silent).

guscost 9y ago
If the documentation says it is a REST API, you could be justified in expecting all POST requests to be non-idempotent, and all other requests to be idempotent. But it would still be reassuring to see this stated explicitly!
- bbarn 9y ago
  That's only if all calls are isolated to simply modifying state of objects, and not causing events. For example, if doing a PUT on a user to change their email kicks off an email to verify the account, then it's not idempotent in my mind.
  - heavenlyblue 9y ago
    Come on: that’s easily fixable if the provider cares: just assign an ID to every mutation operation. Never repeat the operation if called again. In the real world even bigger players such as AdWords would time out on our bulk requests to them if making >100M changes, without giving any errors back (the jobs just simply tend to disappear; or the jobs never get submitted in the first place). Truth is, you may or may not be discussing the appeal of the REST; but the issue in this context is solved already - and it’s only a matter of professionalism and therefore, the resources required to build something that just works. But in the real world we get stoned students writing the majority of the APIs; having read a few how-to’s.
    - bbarn 9y ago
      I don't disagree, the original question was how to vet an API though, and I think it's a valid thing to look for.
  - guscost 9y ago
    It could be argued this is a departure from the standard, but on the other hand allowing PUT to have side-effects might be more user-friendly than an extra POST to a special "email invitation" resource. Would you prefer to see this behavior (as long as it was documented)?

enraged_camel 9y ago

Off-topic: Regarding Stripe's sandbox, I really dislike their web GUI. After creating a bunch of test customers for instance, deleting them requires going into each and every single customer and then clicking "Delete". There is no way to multi-select and batch-delete. (Yes, it can be done programmatically, but that's not always feasible/practical, especially if I want to keep certain customer accounts alive.) Similarly, after deleting a customer, it takes you back to the customer list, but it's not always up-to-date. Sometimes the front-end can detect that updates have occurred in the list (i.e. something has been deleted) but it requires a manual refresh.

codegeek 9y ago
Funny but I agree with you about Stripe's dashboard GUI. They could do better.

dehrmann 9y ago

> Do they use REST or not Meh. REST semantics really only works well when you're doing CRUD operations. They get clunky when something's modeled around actions rather than entities. That said, make sure their response codes and methods make sense.

majormajor 9y ago
Spinning this a slightly different direction: think about what their API operation model is, and how well it lines up with your current and (more importantly) expected future use cases? If you expect that you might need to significantly change what you're doing in the future, having a more simple, composable model around resources that you can call as you need might save your ass down the line compared to if they model things as specific RPC use cases and you find yourself needing a particular variation they don't support out of the box.
zkomp 9y ago
I agree in the sense rest is not as imortant as say: is the api XML or JSON? I’ve integrated many B2B APIs which tend to be varying degrees of XML, plain and sane to rabbithole insane or worst of all SOAP which apparently is really still a thing people use and take seriously in B2B api context. Sigh, xml hard at work solving a problem we never seen, but creates such a bloted horrible mess where json would have been simple and better.
- dehrmann 9y ago
  I see both sides. The magic of SOAP is you can give a tool a WSDL and it will generate bindings in a language of your choice. The downside is it has to be pretty complicated to enable the magic, so building it can be complicated, and debugging it is a nightmare. You could say the same about a lot of modern JS, and that's been somewhat solved by amazing tooling.
  - zkomp 9y ago
    Yes absolutely: this very magic is precisely what is so horrible and imho a rabbithole of insanity. It is CORBA resurrected with XML. In my data oriented mind, the primary thing that matters is the data that is sent, the second is other semantics like idempotency. Neither SOAP nor XML solve or helps: there might be no wsdl bindings in your language, or they are badly implemented (true in my experience). XML make people nest structures where it could have been flatter, SOAP even more, and annotates everything whithout a need for that. This cost for no reason but to entertain the CORBA like pipe dream, or should I say nightmare. We just resorted to pulling out data from xml with xpath. And more or less template the response back, no wsdl and very simple. But why inflict this pain on your API users?

jholman 9y ago

#4 (REST) should not be on this list. There are (at least) three senses of "REST" in use in the development world, and none of them are important in an API. The first is the original definition, laid out in Fielding's thesis. (Normally I call this "the correct definition".) This includes requiring HATEOS, which is far from a necessary property in a good API, and arguably a bad feature because it increases payload sizes. The next is the definition popularized by Rails [1]. This is never precisely outlined anywhere as far as I know, but most people seem to think it requires using URLs with particular patterns (to see an example, just do `rake routes` on any Rails project that doesn't use weird custom routing in routes.rb). Also most people seem to think it requires using PUT for overwriting updates and DELETE for deletions. All of these conventions are not-bad. But they're also not particularly good; they amount to a variable naming convention that happens to be pretty reasonable. Other systems of organization are also perfectly good! But anyway, this is not an important feature in an API. The third definition you'll see sometimes is "our API uses HTTP, therefore it's REST, we're buzzword-compliant". Fuck your buzzword compliance, no that doesn't make your API RESTful. And in some cases, these bozos can't even use HTTP correctly (for example using GETs for side-effect-ful requests). This is pretty much indefensible, but it'll still happen. So if you DO care about one of the first two definitions, don't take it on faith that someone who says "our API is RESTful" knows what that even means. Also, the first two definitions both work in terms of "representations of resources", and all three of the above apply to HTTP [2]. It's not at all clear that either of these are good features in an API. They both have the advantage that they make implementation more predictable, so that's often (usually? almost always?) a great idea. Yay! But resource-representation is a bit bloaty, and so is HTTP, so for some situations, it's more appropriate to discard either or both of those design parameters. For example, suppose you're monitoring some terrifyingly dense IoT deployment, and you want your swarm of sensors to send updates ten times a second. Differential updates over Apache Thrift (or over Google Protobuff) is certainly not over HTTP, and you have to squint pretty hard to to see the differentials as resources. (Mind you, you'd probably also want to send some checkpoints less-frequently, and you could characterize these as resources without too much difficulty.) In summary: REST means different things to different people, and there's a lot of good sense in those communities (I mean, not the third-listed liars, but the other two). BUT, probably you don't actually care about RESTfulness per se, in that cute conventional URI/path patterns are unimportant, and HATEOS is somewhere between nice-to-have and undesirable. HTH Footnote 1: I'm not claiming that authors of Rails (DHH et al) were confused about the definition of REST. As far as I can tell, when they said "make your routes RESTful", they weren't claiming that doing so necessitated using their cute method/URI convention, they were simply claiming that doing so was compatible, and that following some convention is a good idea, and here's a good convention. Yay! Well said! Unfortunately most people who wrote simplifying articles on the subject got it wrong, so now we have an industry full of semi-literates quoting non-existent scripture. Footnote 2: Strictly speaking Fielding's thesis is about what he thinks HTTP did well, and is intended to be largely advice to designers of future protocols intended to compete with HTTP. That's why so much of the "architectural style" is about stuff that's built into HTTP, such that the designer of an HTTP API cannot fuck it up. API authors are not the primary intended audience of the thesis!