
Ask HN: What is your go-to example for a good REST API? - goostavos
I tend to always look to api.github.com when I need a little inspiration.<p>Anyone have some good examples of a particularly well laid out API?
======
sc00ty
Stripe. Their docs are amazing too, I always find it a pleasure integrating
their API.

[https://stripe.com/docs/api](https://stripe.com/docs/api)

~~~
madelinecameron
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.

~~~
guayosr
(I work at Stripe.)

Although it’s kind of proving your point that the API could be easier to
use/better documented, here are some simpler ways to do what you’re looking
for:

* Upgrading a plan (no cancellation needed): [https://stripe.com/docs/api#update_subscription-plan](https://stripe.com/docs/api#update_subscription-plan)
    
    
      > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d plan={new_plan}`
    

* Canceling a subscription at the end of the billing cycle (no need to handle on your end): [https://stripe.com/docs/api#update_subscription-at_period_en...](https://stripe.com/docs/api#update_subscription-at_period_end)
    
    
      > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -X DELETE -d at_period_end=true`
    

* Anchoring subscription to a date (sorry! :( , this is undocumented but should be out soon): [https://stripe.com/docs/api#create_subscription](https://stripe.com/docs/api#create_subscription)
    
    
      > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d billing_cycle_anchor={timestamp}`
    

That said, agreed overall that our subscriptions support needs some love.
We're starting to spend more time on exactly this, so would love any feedback
you (or anyone else reading) are willing to share. I'm eduardo@stripe.com.

~~~
hoodoof
Is this in an obvious place in the docs or in an FAQ?

~~~
guayosr
\-
[https://stripe.com/docs/api#subscriptions](https://stripe.com/docs/api#subscriptions)

\-
[https://stripe.com/docs/subscriptions/guide](https://stripe.com/docs/subscriptions/guide)

------
taf2
Twilio - they have a great API.

And in 2008/9 their API was always given as an example for REST APIs done
right and it's still true today

[https://www.twilio.com/docs/api/rest](https://www.twilio.com/docs/api/rest)

~~~
tbrock
Twilio is one of the worst. The documentation leaves out crucial details some
of the time and an XML interface for phone calls? Gross.

------
rdegges
Stormpath. [https://docs.stormpath.com/rest/product-
guide/latest/referen...](https://docs.stormpath.com/rest/product-
guide/latest/reference.html)

They do an excellent job of providing a clear and robust API. I work there
(but not on the engineering team), and still genuinely love the API itself.

~~~
swaroop
I love the JSON+REST API talk by their CTO -
[https://youtu.be/hdSrT4yjS1g](https://youtu.be/hdSrT4yjS1g)

------
davidgh
The key to a great API? Have the developer / designer of the API write the
first set of client applications before the API is published externally. I
have integrated with many dozens of APIs over the years and it is immediately
obvious (and unfortunately too common) when the designer of the API has never
been in the seat of the client developer.

Sorry for not pointing to specific examples, but things I really love to see
in an API:

\- Fully qualified URLs in all links (makes navigating and discovery in
Postman a breeze).

\- Ability to expand resources represented by links (even deeply nested
resources) so I can get exactly what I need in a single request.

\- The ability to specify what parts of the response resource to include /
exclude, allowing me to slim the response to exactly what I need. More
important in clients running on mobile devices where slender responses make a
noticeable performance difference.

\- The exact same URLs (including hostnames) for the test and production API,
the difference between the environments being determined by the credentials
used in the request. This greatly simplifies code in the client test and
production environments.

\- Security schemes that allow me to write serverless client applications
(OAuth 2 implicit grant). This certainly requires more work by the API
developer, but makes it possible to crank out all sorts of useful tools
quickly, and massively reduces client IT overhead. This may not be appropriate
for all APIs, but could be used a lot more often than it is.

\- Along with the above, support for CORS so we don't have to mess around with
JSONP and other hacks in the browser.

\- If you make me eat your timezone, please _please_ make it UTC. But spend a
little extra effort and allow me to pass a timezone in, either as an account
settings and/or request parameter (and a simple offset isn't good enough -
support actual timezones so daylight saving is handled). It can be incredibly
hard to analyze data in responses when you're constantly having to translate
the time to your own to give proper context. Timezone support isn't fun but
libraries make it pretty easy. This is more important in APIs that provide
lots of transactional data.

\- Let me attach meta data to resources - it doesn't even have to be a lot.
Sometimes allowing me to slip in a handful of bytes removes the need for an
entire database on my side.

\- Be painfully explicit in error responses. State the obvious, especially in
errors that are likely to occur at the beginning of integration such as issues
with authentication, content types, payload structure, etc.

~~~
zeisss
> \- Let me attach meta data to resources - it doesn't even have to be a lot.
> Sometimes allowing me to slip in a handful of bytes removes the need for an
> entire database on my side.

So much +1's for this. Even better if I can query for it.

------
whoisjuan
Plaid API! So well done and documented IMHO:
[https://plaid.com/docs/api/](https://plaid.com/docs/api/)

~~~
madelinecameron
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)

~~~
charleyma
Hi Madeline - Charley from the Plaid growth team here. Totally get where
you're coming from in regards to pricing, we're working on a bunch of
improvements to the site, of which pricing is at the top of my list to get on
there! So that will be on there soon :)

If you have any other questions, feel free to reach me directly at
charley@plaid

~~~
madelinecameron
Ha! You are actually the person I got in contact with when I complained to the
help email.

You were very helpful! I am looking forward to having access to more banks!
(If that is in the plan)

------
shireboy
Trello's is fairly nice: [https://developers.trello.com/advanced-
reference/card](https://developers.trello.com/advanced-reference/card)

~~~
dfischer
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.

~~~
Croaky
I _love_ Trello and have built a few things on their API but have to agree the
API docs are painful, hard to navigate.

Also, what's up, homie? Hope you're well.

~~~
dfischer
Dan? Hi! Hope you're well!

------
kaendfinger
Digital Ocean's API is nice.

[https://developers.digitalocean.com/documentation/v2/](https://developers.digitalocean.com/documentation/v2/)

------
mcphilip
Google Drive's REST API documentation is a good place to start:

[https://developers.google.com/drive/v2/reference/#Children](https://developers.google.com/drive/v2/reference/#Children)

~~~
baudehlo
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.

------
bryanlarsen
Related: anybody have some good examples of a good asynchronous API? This
claims to be the standard, but it has confused many of our customers.
[http://restcookbook.com/Resources/asynchroneous-
operations/](http://restcookbook.com/Resources/asynchroneous-operations/)

To summarize: send a 202 for the initial request, redirecting to a job URL.
The client polls on the job URL, which returns 200 with progress information
until it's done, when it returns a 303 redirecting to the final output.

One particular problem spot is that many http libraries automatically follow
the 303 redirect, and some even follow the 202 redirect.

I definitely think we would have been better off just putting status and final
location information as JSON attributes in the body rather than putting it in
HTTP response codes and Location headers. Non-standard, but much less
confusing for our customers.

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

~~~
kasey_junk
All push models are poll models down an abstraction layer.

~~~
infinite8s
And all computations can be modeled as Universal Turing Machines at some
level. That doesn't mean it's the most useful level at which to analyze the
semantics of what you are trying to accomplish.

~~~
kasey_junk
Sure but saying something isn't asynchronous because its polling is flat
wrong.

------
seanplusplus
The Slack API is a thing of beauty

[https://api.slack.com/](https://api.slack.com/)

~~~
dxhdr
I think it could use improvement. Look at
[https://api.slack.com/methods/chat.postMessage](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!

------
huherto
Follow up. Anyone care to recommend a good book or reference on good design of
REST APIs?

~~~
veesahni
I collated a list of best practices here:

[http://www.vinaysahni.com/best-practices-for-a-pragmatic-
res...](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

~~~
mcobrien
I read this after patio11 linked to it. It's an amazing resource, thank you!

------
supergeek133
Twilio does a pretty good job as well.

~~~
w00kash
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?

~~~
taf2
It used to always be cited as an example of a good REST API see this same
question from 7 years ago and you'll see Twilio is top recommended
[https://news.ycombinator.com/item?id=867972](https://news.ycombinator.com/item?id=867972)

Oh and still is today because it's a good API - timeless

------
pokstad
CouchDB! [http://docs.couchdb.org/en/1.6.1/http-
api.html](http://docs.couchdb.org/en/1.6.1/http-api.html)

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

------
bjourne
I've been using flask-restless to good effect. Then you don't build your own
api at all, you just generate it based on your database model. You get urls
like /persons/23/edit, /persons/77/delete and so on by free. There is also
Django restless which is pretty good too.

[https://github.com/jfinkels/flask-
restless](https://github.com/jfinkels/flask-restless)

~~~
bjornedstrom
That doesn't seem like a good example at all.

Instead of /persons/23/edit, maybe POST /person/23

Instead of /persons/77/delete, maybe DELETE /person/23

~~~
rahkiin
/persons/23/edit would become PUT /persons/23, while create would be POST
/persons.

------
Cieplak
REST implies HATEOS. If you can't use an API response to navigate to other
resources of the API, I wouldn't consider that API RESTful.

Also, verbs are not RESTful. Verbs imply an RPC interface.

RPC (verb):

    
    
        POST https://<payments-api>/card_authorizations/<id>/capture  
    

REST (noun):

    
    
        POST https://<payments-api>/card_authorizations/<id>/charges

~~~
ossm1db
A thousand times yes. There are too many APIs which claim REST without even
knowing what it means.

~~~
spriggan3
HATEOAS is a pain in the ass to implement, people know what it means, they
just don't bother implementing it. It's often not a necessary feature for an
API. HATEOAS is even more painful when using JSON, a format that doesn't
really support metadatas ( a link is meta compared to a ressource ) and very
little clients are built with HATEOAS in mind.

The REST paper has good ideas, and people are picking and choosing what they
want. There is no REST specification that makes HATEOAS mandatory. Maybe Roy
Fielding should have written one on top of HTTP to make it clear what it is
about instead of writing an dissertation.

How do you represent a link semantically? 100 businesses will have 100
different answers. That's why, by the way, HTML was so ingenious. HTML tags
ARE semantic. If Roy came with a core set of tags describing things then
people would know how to write basic HATEOAS APIs.

So don't blame the people, blame the absence of a clear specification(and no,
the REST paper is not a spec, a spec is normative).

All this shouldn't matter as long as every IS documented. HATEOAS can't
replace a good documentation. Today, for most developers REST is about urls,
verbs and caching + a few other headers, nothing more.

------
Pelerin
Shopify is pretty nice:
[https://help.shopify.com/api/reference](https://help.shopify.com/api/reference)

------
AhtiK
PostgREST is a standalone web server that turns your postgresql database
directly into a RESTful API.

The REST API is designed intuitively, just as one would expect.

I've been using it a lot for prototyping and internal applications. Now with
the help of native row level security from postgres, it would become also a
good choice for production. Or just wrap it behind your gateway.

[http://postgrest.com/](http://postgrest.com/)
[http://postgrest.com/api/reading/](http://postgrest.com/api/reading/)
[http://postgrest.com/api/writing/](http://postgrest.com/api/writing/)

------
georgewfraser
OData! So underused. [http://www.odata.org/](http://www.odata.org/)

~~~
matmo
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...](http://services.odata.org/V4/TripPinServiceRW/People\("russellwhyte"\)/Trips\(0\)))

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

~~~
ako
Odata is à standardized rest use case for generaal purpose data access, so
client tools can use it out of the box. Something like sql but over http. Some
tools that provide odata support: tableau, tibco spotfire, linqpad, excel.

Excel is a nice example, you can have a sheet with data pulled in over odata
from any app that supports odata.

------
wozer
Related question: Does a REST API make sense for an internal interface? Or is
the overhead prohibitive compared to a more specialized interface?

(By internal interface I mean: an interface that is used only by the team that
created it)

~~~
blowski
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.

~~~
rimantas
I'd argue that it removes complexity, not adds it.

------
icco
Flickr still has one of my favorite APIs:
[https://www.flickr.com/services/api/](https://www.flickr.com/services/api/)

------
spencera
I also find GitHub to be a great example for API design inspiration

------
cnnrjcbsn
BlockScore.
[https://docs.blockscore.com/v4/curl/](https://docs.blockscore.com/v4/curl/)

------
rcpt
Not exactly an api but nice to see some common patterns
[https://getkong.org/](https://getkong.org/)

------
milansm
[http://api.zalando.com](http://api.zalando.com) is quite self explanatory.

------
w8wut
[http://developer.okta.com/docs/api/getting_started/design_pr...](http://developer.okta.com/docs/api/getting_started/design_principles)

Good error handling, easy to get started, and they provide Postman collections
for each API

~~~
strictnein
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?

~~~
dpcx
To make it absolutely obvious everywhere in your code that you're talking
about an errorSummary, not just a summary?

------
niftich
The Sun Cloud API [1] was specifically designed to adhere to REST as close as
possible, including HATEOAS. Here's some background from Tim Bray [2], who
worked on this API when he was at Sun [3].

[1]
[https://kenai.com/projects/suncloudapis/pages/Home](https://kenai.com/projects/suncloudapis/pages/Home)

[2] [https://www.tbray.org/ongoing/When/200x/2009/03/16/Sun-
Cloud](https://www.tbray.org/ongoing/When/200x/2009/03/16/Sun-Cloud)

[3]
[https://en.wikipedia.org/wiki/Tim_Bray](https://en.wikipedia.org/wiki/Tim_Bray)

------
hoodoof
Question: to what extent does it really matter that an API closely meet the
REST best practices?

------
Yhippa
Washington Metropolitan Area Transit Authority API:
[https://developer.wmata.com/docs/services](https://developer.wmata.com/docs/services)

------
foolinaround
Follow up question:

is there a good example of an OPEN SOURCE REST API?

I would like to see how the versioning is achieved, how the versions are
incremented, etc?

Bonus points if it is in the Java ecosystem.

~~~
buremba
We have been using Swagger and developed a REST API library [1] in Java that
automatically generates Swagger specification for your API using static
analysis. We can also automatically generate client libraries
([https://github.com/buremba/rakam-client](https://github.com/buremba/rakam-
client)) and API documentation ([http://api.rakam.io/](http://api.rakam.io/))
from Swagger specification. Currently, the library lacks documentation but it
can at least give you the idea.

[https://github.com/buremba/netty-rest](https://github.com/buremba/netty-rest)

~~~
wing328hk
The latest version of Swagger Codegen ([https://github.com/swagger-
api/swagger-codegen](https://github.com/swagger-api/swagger-codegen)) also
automatically generates documentation (markdown) for API clients/libraries,
e.g. installation, getting start, doc for API endpoints and models.

Here is an example: [https://github.com/wing328/test-java-
okhttp](https://github.com/wing328/test-java-okhttp)

Please pull the latest version and give it a try.

~~~
buremba
Nice! Instead of generating Markdown files, you could also generate full HTML
documentation similar to Slate. The generated Markdown files can be used in
Slate since the format seems to be similar. Actually I opened an issue in
swagger-codegen repo ([https://github.com/swagger-api/swagger-
codegen/issues/1387](https://github.com/swagger-api/swagger-
codegen/issues/1387)) and we talked about it. The reason that I created a
separate project is that the the example usage section and the format didn't
seem to be implemented as language in swagger-codegen.

~~~
wing328hk
I notice that you put all the clients (C#, Java, Ruby, PHP, etc) under the
same Github project.

I would suggest you to create separate Github repo for API clients in
different languages so that developers can install the PHP, Python, Ruby, etc
API clients directly from the Github repo.

You can leverage "git_push.sh" to push the auto-generated SDKs (with doc,
sample code) to Github.

------
jc4p
Are we just talking about API documentation? Stripe's the obvious go-to for
that, but for big business stuff I was pleasantly surprised with HubSpot's API
and documentation. Their own UI uses the API, which means debugging a lot
easier I think:
[http://developers.hubspot.com/docs/overview](http://developers.hubspot.com/docs/overview)

------
cheez
Atlassian has a great process around developing their REST APIs. It was a bit
random in earlier iterations but that team has come into its own.

------
alexmingoia
Xero. The docs are accurate and complete. The API is consistent. The API works
as documented. The API is capable of everything the webapp does.

[https://developer.xero.com/documentation/api/api-
overview/](https://developer.xero.com/documentation/api/api-overview/)

~~~
cyberferret
EXCEPT for the fact they decided to use .NET date formats throughout their API
rather than the more traditional ISO date formats. (I do like that they
sheepishly apologised for this in their API docs).

Also, they are usually a few months behind releasing API coverage of new
features and modules.

Also, it is a bit fiddly having to specify a 'scope' parameter when
authenticating yourself for the API otherwise you won't be able to access
certain data.

Lastly, I don't like the way there is almost a separate API for the AU and US
version of Payroll. I get that they are fairly different beasts, and that they
are actually third party systems that have been 'integrated' in, but I wish
they had more commonality.

------
heironimus
Not a comment on the API itself, but I like how Stackoverflow/Stackexchange
has interactive documentation, allowing you to fill in prompts and have it
create the request for you and show the live results.

[https://api.stackexchange.com/docs](https://api.stackexchange.com/docs)

------
programmarchy
zettajs [1] is a great example of a REST API that meets the HATEOS
requirement.

[1] [http://www.zettajs.org](http://www.zettajs.org). "An API-first, open
source software platform for the Internet of Things."

------
claudinho
Smart2Pay has a pretty neat REST API documentation.
[https://docs.smart2pay.com/category/getting-
started/](https://docs.smart2pay.com/category/getting-started/)

------
abakker
SurveyMonkey has a very good setup - pretty much anything you can do with
their web app, you can also do via the API.
[https://developer.surveymonkey.com](https://developer.surveymonkey.com)

------
westoque
Coinbase.
[https://developers.coinbase.com/api/v2](https://developers.coinbase.com/api/v2)

\- Documentation is complete and concise.

\- Responses are consistent (in terms of data structure)

\- Status codes are consistent

------
nwatson
I like this document: [http://restful-api-
design.readthedocs.io/en/latest/](http://restful-api-
design.readthedocs.io/en/latest/)

~~~
t0mbstone
"URLs should never be constructed by an API client. Instead, the client should
only follow links that are generated by the API itself."

I really hate this notion. It makes jumping to page 100 of a 345 page result
set impossible. You would literally have to follow 100 pages, or have some
ridiculously long index with 345 separate links.

I believe that it should be possible for an API to document a URL formula, and
rely on the API client to follow that formula to generate a URL.

That's where things get sticky, though, because as far as I know, there's no
good standard defined for how an API can document a dynamic URL formula that
is programmatically discoverable.

~~~
jessaustin
I'm not sure whether it's a "good" standard, but that doc indirectly links to
"URI Templates" [0] It isn't clear to me how that works on the client side
however. Can we just assume that clients know how to construct a URI using a
template? I guess we can, since it's no more difficult than using the specific
API knowledge required to "jump to page 100" as you want to do.

[0] [http://tools.ietf.org/html/rfc6570](http://tools.ietf.org/html/rfc6570)

------
kevindeasis
I'd like to ask a complementary question!

What resources (books/blogs) are you guys/gals looking at that talks about
best practices for creating/implementing great REST API endpoints?

------
elviejo
I always found Flickrs api to be easy to use, and well documented

------
shravvmehtaa
[https://lob.com/docs](https://lob.com/docs).

I'm an engineer at Lob. We'd love any feedback! support@lob.com.

~~~
fapjacks
Your documentation is great! You've got straightforward authentication,
prominent curl examples, expected responses, clear-cut explanations of
expected inputs... I think your API looks fun and easy to use! I don't send
physical mail, but if I did and tried your API, I would probably get in
trouble for mail-bombing hate mail to my elected officials.

 _Hey, wait a minute!_ Those examples are using test credentials... Your API
responds to those curl calls with real output, and the output matches what
your documentation says it should be. Okay, that is awesome! Also when I force
myself to get rate-limited, my requests fail gracefully with a "429 Too Many
Requests" and a descriptive error, which is refreshing. Nice API!

------
jgalt212
The Bloomberg OpenFIGI API is very clean.

[https://www.openfigi.com/api](https://www.openfigi.com/api)

------
tvvocold
Check this if you know Chinese:
[https://open.coding.net](https://open.coding.net)

------
junto
I was quite impressed by the Rackspace API:

[http://api.rackspace.com](http://api.rackspace.com)

------
j45
I like Stripe, but the design of an API is not always cookie cutter.

A lot has been written on API design that makes for interesting reading.

------
aaronhoffman
Any OData love? [http://www.odata.org/](http://www.odata.org/)

------
ranyefet
JSON API spec is really good [http://jsonapi.org](http://jsonapi.org)

~~~
jerhinesmith
JSON API seems overly verbose to me. It feels like like a direct descendant of
the SOAP / WSDL era -- or maybe I'm just scarred from having written and
consumed SOAP webservices.

~~~
Shicholas
It is somewhat bloated, but it's predictable bloatness, which I'm perfectly
fine with.

------
BinaryMachine
JSON API! [http://jsonapi.org/](http://jsonapi.org/)

------
Shicholas
Jsonapi.org I feel this embodies every trope of building web apps (well at
least ones that use HTTP 1.1)

------
perseusprime11
Based on the comments, this thread can also serve as your go-to example for
the worst REST API...

------
thejerz
The JIRA API is pretty good.

~~~
hliyan
Agreed:
[https://docs.atlassian.com/jira/REST/latest/](https://docs.atlassian.com/jira/REST/latest/)

------
LeicaLatte
if you are looking for data aggregated around time wakatime has a good take -
[https://wakatime.com/developers](https://wakatime.com/developers)

------
einrealist
Roy Fieldings dissertation.

If a client starts to construct URIs, then there is a flaw.

~~~
SilasX
So every accessible URI must be explicitly presented to the client? Even when
there are trillions of possible combinations of settings?

~~~
einrealist
Does your browser need all the ressources of the Internet at once?

~~~
SilasX
No; nor does it need the overhead of having to navigate through several lists
to get to the desired URI when it could infer the full URI from the very
beginning.

~~~
einrealist
You are free to type in any URI you like. In fact, a REST client can save
links (bookmarks) or cache payloads that contain these links / forms
(templates). But don't expect the server to not change things. So being able
to navigate is a form of resilience. For me, thats worth to have with what you
call "overhead". I call it a sane tradeoff.

~~~
SilasX
Inferring the URI rather than pointlessly downloading ten end points to walk
the full options list every time, also seems sane; the former doesn't seem
like "doing it wrong".

Caching doesn't solve the problem of "what if I want to look up the travel
time between this other city and this other city via this other means".

~~~
einrealist
What do you mean to look up travel times? I'd provide a resource that you can
POST to and the server computes the travel time. There is no caching useful
here. But way to create the request (like a form) can be provided by a
document. And this document can be cached by a client.

~~~
SilasX
The request will be idempotent so it shouldn't be a POST. But if it's a GET,
then you're telling me I shouldn't tell the client where to put the start and
end city in a request URI?

~~~
bbcbasic
In theory you could have a query that return a list of cities and a url for
each, with that url being a query to get you the second city list.

~~~
SilasX
Right, which means that if I followed the REST principle (clients don't
construct URIs), then every request must make an extra, unnecessary round trip
for every parameter. Which sounds quite pointless.

~~~
bbcbasic
Yes sounds like it. Plus if the option is a geo coordinate then it's
impractical to list them all. I don't see the problem with meta data or
assumed knowledge.

------
hoodoof
Sometimes needs a few refreshes to load for some reason but this is an
interesting one to look at:

[https://developer.godaddy.com/doc](https://developer.godaddy.com/doc)

------
herbst
Twitter v1 was amazingly simple and well documented.

------
wraith69
I use the FDA's 18f API and the Jsend standard.

------
kwikiel
Anything scaffolded by rails.

~~~
rimantas
In case some don't take this seriously: it is true. Rails does pretty good job
in this recard. It is not HATEOAS, bet otherwise it pretty solid and follows
best practices quite well.

~~~
bbcbasic
HATEOAS. [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven). I read this and still have no clue!

------
digitalpacman
Github

------
coroutines
I'm actually using the responses here as a hunting ground for companies I'd
like to work for.

Carry on...

------
emorse
I like tumblr's api

------
aioprisan
Trello and Stripe.

------
loadfocus
[https://dev.twitter.com/rest/public](https://dev.twitter.com/rest/public)
Twitter's APIs are quite useful in terms of indentifying the REST patterns:
stateless, resources names etc

------
thesimpsons1022
i can tell you a bad one: Yammer

