Ask HN: What is your go-to example for a good REST API?

Nice stuff.

One nitpick: it always feel weird to me to have an error (or any other object) where the attributes are named like this:

    {
        "errorCode": "E0000001",
        "errorSummary": "Api validation failed",
        "errorLink": "E0000001",
        "errorId": "oaeHfmOAx1iRLa0H10DeMz5fQ",
        "errorCauses": [
            {
                "errorSummary": "login: An object with this field already exists in the current organization"
            }
        ]
    }

Why have "error" in there at all?

^ Came in to say this. I use Stripe for inspiration on their API, docs, and even the general UI/UX to get a feel for something simple yet elegant.

nit picking devil's advocate: not all of the API is documented. There are some features that exists, but you have to know about. Granted, this is intentional. e.g.: "billing_cycle_anchor" in the subscription API.

+1 for Stripe. BlockScore is another one similar to Stripe in terms of docs and intuitive design.

Nooooooooo.

I dislike Stripe's API. There are parts of it that just make no sense.

Say, you want to set a billing date for that fancy subscription. Yeah, just set a trial date until the billing date you want. Oh, and don't forget to charge a prorated difference (by hand, with charges)!

Want to upgrade that subscription? Yeah, cancel that subscription and start a new one. Oh, and don't forget to set that trial again!

Want to cancel that subscription but not until their next billing date? Hahaha, yeah no. You need to cancel now through Stripe and set up a process to cancel on your side. (Not the biggest complaint, but really. If I am having Stripe manage my subscriptions, they should do it all)

And I am sure there are many other details which would also drive me mad.

With all of that said, I think Stripe's API is definitely one of the better ones since my complaints are more functionality / feature requests than complaints about how it is set up.

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d plan={new_plan}`

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -X DELETE -d at_period_end=true`

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d billing_cycle_anchor={timestamp}`

-1 for Stripe. The API is designed without any thought how the use cases need to use it. Leaks the JSON structure of the document to the client. This breaks your code when they change the JSON structure.

+0.

Some parts are great, other parts not so much. My thoughts echo the other's here.

I feel like their API isn't super uniform in a lot of the ways it's integrated, but I will give them a +1 for allowing very easy versioning.

Even better is the realtime support on their IRC channel.

Sadly, Stripe API is not so great :(

It seems like the API is way too complex to do certain operations. Especially some very common use cases: for example, how to apply discount for next year for customers who already have subscription (we wanted to emulate how Comcast always gives you discount if you want cancel and took us weeks to make that working ...). I think they do want to fix all these issues but API is not designed to be easily expandable.

It's actually very hard to find a decent REST API :(

My points here are the following:

1. Think very very hard about how people will use your API <-- this is critical. This also includes operational characteristics of your API (performances, how often it is going to be called, optimization, etc.)

2. Make API easily expendable. Especially relationships between models. Sometimes, it is ok (or even better) just to organize it as "SQL wrapper". Like SOQL by Salesforce - but that again depends on number 1.

I came here to say this. I recently built a pretty tight integration between Trello and our app, and using the API was quite pleasant. The documentation isn't stellar (it has examples for requests, but not responses, s you need to use trial and error), but everything is standardized, so once you figure out the logic, you're golden.

I actually found Trello's API to be one of the worst most non-compliant restful API's I've seen. Nothing about it is restful with the extra actions they have on resources. It's hard to follow. The docs are sub-par too.

+1 for CouchDB. Especially if the application is largely data driven

My employer (Apigee) makes a good introductory ebook on this topic. Be forewarned this is a huge topic with many (strong) opinions on what 'good' REST actually is.

http://apigee.com/about/resources/ebooks/web-api-design

REST in Practice[1], Building Hypermedia APIs with HTML5 and Node[2] and Designing Hypermedia APIs[3].

1. https://www.amazon.com/REST-Practice-Hypermedia-Systems-Arch...

2. https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/d...

3. http://www.designinghypermediaapis.com/

My coworker just bought this and loves it. https://leanpub.com/build-apis-you-wont-hate

The examples are PHP-based and there is an active Slack channel supporting the book.

I collated a list of best practices here:

http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...

Make sure to read the Fielding Dissertation to understand what REST actually is.

i wish all of their APIs were this nice.

It's ok but once you start implementing things it gets a bit hairy. Mostly because folders aren't really folders in their API, even though they are in every app that uses them. And their search API to find folders is flaky at best, as it's a consequence of the above problem.

If you have to poll then it's not asynchronous. A better design would utilize something like webhooks.

DigitalOcean's API does this in quite a few spots [1] - it calls the async jobs "actions", but they signal completion of jobs performed on base objects.

[1] https://developers.digitalocean.com/documentation/v2/

The short answer is that there is really no good general purpose way to deal with asynchronous communication in a "restful" HTTP API. All solutions have major drawbacks. This is one of the biggest shortfalls of rest/http in my experience. People tend to switch to other protocols to address these use cases (this is a common reason for adopting message bus infrastructure like Kafka as part of a SOA).

I like where Plaid is going but it bothered me that they are coy about their pricing.

Typically when a company refuses to say their price or says "Contact Us", that means "Prepare your wallets".

With that said, very economical. I think it was something like $0.10 per account you add. I am looking forward to Plaid expanding what banks are offered since currently they only work with 10 or so (although if they pick you, they give you access to a few thousand more. Not sure the criteria)

Not a big fan of Accounts being structured differently based on product.

Agreed: https://docs.atlassian.com/jira/REST/latest/

I think it could use improvement. Look at https://api.slack.com/methods/chat.postMessage and explain how "as_user" makes any sense. And it gets more convoluted depending on other parameters used (IM channels, etc.)

Also, why can't I use a secret key with my basic postMessage script? I have to navigate OAuth2 just to make a post? Argh the pain!

Just curious. What do you think it is that makes twilio a good example of a REST API? Other than the fact that they have one?

What is OData? The website does a poor job of explaining it from a high level. The only discernible feature I see is adding "functions" to url's (ex: http://services.odata.org/V4/TripPinServiceRW/People("russel...)

I've seen "OData" mentioned here and there, but I've never understood the difference between OData and a classic REST API.

Maybe. It adds a whole layer of complexity, but it might be worth it. Depends on your team's structure and relevant experience, and on the details of the project.

I think it's more maintainable and easier to test

It depends on the problem - if the particular interface is semantically suitable for REST, then there won't be any overhead and REST will just be a useful convention on how exactly you should represent it; and on the other hand if that particular interface needs are not suitable for REST then you probably should implement it with RPC, message queues or whatever other option better suits the problem instead of trying to mangle it into REST paradigm.