15 ms·
Ask HN: What is your go-to example for a good REST API?
I tend to always look to api.github.com when I need a little inspiration.
Anyone have some good examples of a particularly well laid out API?
- w8wut 10y agohttp://developer.okta.com/docs/api/getting_started/design_principles http://developer.okta.com/docs/api/getting_started/design_pr... Good error handling, easy to get started, and they provide Postman collections for each API
- strictnein 10y agoNice 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 10y agoTo make it absolutely obvious everywhere in your code that you're talking about an errorSummary, not just a summary?
- abakker 10y agoSurveyMonkey 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
- sc00ty 10y agoStripe. Their docs are amazing too, I always find it a pleasure integrating their API. https://stripe.com/docs/api https://stripe.com/docs/api
- jxm262 10y ago^ 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.
- mrgalaxy 10y agoJeez, glad I'm not the only who feels Stripe's API is basically the golden standard when it comes to a properly implemented REST API and documentation.
- jdc0589 10y agonit 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.
- iLoch 10y ago+1 for Stripe. BlockScore is another one similar to Stripe in terms of docs and intuitive design.
- madelinecameron 10y agoNooooooooo. 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.
- 10y ago
- deleted 10y ago[deleted]
- cnnrjcbsn 10y agoBlockScore. https://docs.blockscore.com/v4/curl/ https://docs.blockscore.com/v4/curl/
- rcpt 10y agoNot exactly an api but nice to see some common patterns https://getkong.org/ https://getkong.org/
- shireboy 10y agoTrello's is fairly nice: https://developers.trello.com/advanced-reference/card https://developers.trello.com/advanced-reference/card
- enraged_camel 10y agoI 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.
- dfischer 10y agoI 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.
- tspike 10y agoCare to contribute one you do find appealing?
- dfischer 10y agoI like stripe / twilio a great deal.
- Croaky 10y agoI 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 10y agoDan? Hi! Hope you're well!
- 10y ago
- jc4p 10y agoAre 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
- pokstad 10y agoCouchDB! http://docs.couchdb.org/en/1.6.1/http-api.html http://docs.couchdb.org/en/1.6.1/http-api.html
- chajath 10y ago+1 for CouchDB. Especially if the application is largely data driven
- huherto 10y agoFollow up. Anyone care to recommend a good book or reference on good design of REST APIs?
- akman 10y agoMy 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 http://apigee.com/about/resources/ebooks/web-api-design
- amjd 10y agoI can vouch for this. It really helped me when I was getting started with REST APIs.
- ethagnawl 10y agoREST 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-Architecture/dp/0596805829/ref=sr_1_1?ie=UTF8&qid=1466797753&sr=8-1&keywords=rest+in+practice https://www.amazon.com/REST-Practice-Hypermedia-Systems-Arch... 2. https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578/ref=sr_1_1?ie=UTF8&qid=1466797771&sr=8-1&keywords=hypermedia+api+node+html5 https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/d... 3. http://www.designinghypermediaapis.com/ http://www.designinghypermediaapis.com/
- specialist 10y ago+1, if you have to do REST, this is the book. Our book study group covered this book a few years ago. This book is rational, its advice actionable. Like "Agile", "REST" is merely a pretext to start an argument. Just do what works, focusing on reducing the cost of change (risk mitigation).
- rimantas 10y agoWhich one? There are three listed.
- aioprisan 10y agoTrello and Stripe.
- Pelerin 10y agoShopify is pretty nice: https://help.shopify.com/api/reference https://help.shopify.com/api/reference
- milansm 10y agohttp://api.zalando.com http://api.zalando.com is quite self explanatory.
- elviejo 10y agoI always found Flickrs api to be easy to use, and well documented
- mcphilip 10y agoGoogle 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
- eonw 10y agoi wish all of their APIs were this nice.
- baudehlo 10y agoIt'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 10y agoRelated: 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 10y agoIf you have to poll then it's not asynchronous. A better design would utilize something like webhooks.
- bryanlarsen 10y agoYes, we have webhooks, and a grand total of 1 of our customers uses them. Setting up an HTTP server just to receive a webhook is a lot to ask. Long poll lets the polling be efficient.
- bjt 10y ago> If you have to poll then it's not asynchronous. Says who? Maybe not "streaming". Maybe not "real time". But certainly asynchronous.
- kasey_junk 10y agoAll push models are poll models down an abstraction layer.
- infinite8s 10y agoAnd 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.
- whoisjuan 10y agoPlaid API! So well done and documented IMHO: https://plaid.com/docs/api/ https://plaid.com/docs/api/
- madelinecameron 10y agoI 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)
- deleted 10y ago[deleted]
- charleyma 10y agoHi 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 10y agoHa! 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)
- mooreds 10y ago> Typically when a company refuses to say their price or says "Contact Us", that means "Prepare your wallets". This, so much. Especially when it is a developer tool, where the switching cost is high because other software sits on top of it.
- thejerz 10y agoThe JIRA API is pretty good.
- hliyan 10y agoAgreed: https://docs.atlassian.com/jira/REST/latest/ https://docs.atlassian.com/jira/REST/latest/
- seanplusplus 10y agoThe Slack API is a thing of beauty https://api.slack.com/ https://api.slack.com/
- dxhdr 10y agoI 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!
- supergeek133 10y agoTwilio does a pretty good job as well.
- w00kash 10y agoJust 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 10y agoIt 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
- supergeek133 10y agoFrom a development perspective it isn't so much the actual API or the structure of it.. but how easy they make it to understand and integrate into it. They have a plethora of getting started guides and examples that make it really easy to 'hello world' quickly. You have to actually dig to get to the reference when you first sign up. Hello world in 30 minutes or less is important for any API program.
- georgewfraser 10y agoOData! So underused. http://www.odata.org/ http://www.odata.org/
- matmo 10y agoWhat 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("russellwhyte")/Trips(0) 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.
- rzzzt 10y agoOData is more or less SQL over HTTP. You get a rich toolbox for selection, projection and transformation of datasets exposed as an OData source (think EBay listings and SQL Server tables and reports), along with the remaining letters of CRUD.
- ako 10y agoOdata 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.
- j45 10y agoI 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.
- wozer 10y agoRelated 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 10y agoMaybe. 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 10y agoI'd argue that it removes complexity, not adds it.
- eecks 10y agoI think it's more maintainable and easier to test
- PeterisP 10y agoIt 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.
- kaendfinger 10y agoDigital Ocean's API is nice. https://developers.digitalocean.com/documentation/v2/ https://developers.digitalocean.com/documentation/v2/
- emorse 10y agoI like tumblr's api
- alexmingoia 10y agoXero. 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/
- skiltz 10y agoNot everything. https://xero.uservoice.com/forums/5528-xero-api/suggestions/340274-import-bank-statement-lines-via-the-api https://xero.uservoice.com/forums/5528-xero-api/suggestions/...
- cyberferret 10y agoEXCEPT 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.
- retreatguru 10y agoTheir per minute rate limiting caused some problems for us. Pretty annoying.
- mb_72 10y agoNope. Try adding a Client Group with no clients via the API - you can't. Xero have admitted that it's a problem, and basically won't commit to ever fixing it. There are another couple of examples relating to problems with the Xero API that don't come to mind right now, but indeed there are problems.
- heironimus 10y agoNot 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
- Cieplak 10y agoREST 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
- deleted 10y ago[deleted]
- ossm1db 10y agoA thousand times yes. There are too many APIs which claim REST without even knowing what it means.
- spriggan3 10y agoHATEOAS 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.
- rimantas 10y agoMany do know. But they just choose one step lower lever on Richardson maturity model as more pragmatic. Yes, according to Fielding that level cannot be called RESTfull, oh well…
- foolinaround 10y agoFollow 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.
- joshmn 10y agoGitLab's done some stuff.
- buremba 10y agoWe 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 10y agoThe 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 10y agoNice! 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.
- ranyefet 10y agoJSON API spec is really good http://jsonapi.org http://jsonapi.org
- jerhinesmith 10y agoJSON 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 10y agoIt is somewhat bloated, but it's predictable bloatness, which I'm perfectly fine with.
- anonova 10y agoHave you actually implemented something following this spec? My experience is that it's somewhat okay-defined for consuming data, but the spec itself is wildly incomplete in the other direction. Looking at the repo and discussion forum, the maintainers are inactive, with tons of open questions unanswered.
- geoffroy 10y agoI implemented two APIs with it, mostly read oriented to be honest. The biggest problem we faced is the lack of maturity of Android and iOS SDKs for it.
- cheez 10y agoAtlassian 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.
- kevindeasis 10y agoI'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?
- deleted 10y ago[deleted]
- deleted 10y ago[deleted]
- nwatson 10y agoI like this document: http://restful-api-design.readthedocs.io/en/latest/ http://restful-api-design.readthedocs.io/en/latest/
- t0mbstone 10y ago"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.
- prodigal_erik 10y agoA search is a resource. We already have media types and schema languages for resources, there's no reason to recreate them for URLs themselves.
- jessaustin 10y agoI'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
- rdegges 10y agoStormpath. https://docs.stormpath.com/rest/product-guide/latest/reference.html https://docs.stormpath.com/rest/product-guide/latest/referen... 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 10y agoI love the JSON+REST API talk by their CTO - https://youtu.be/hdSrT4yjS1g https://youtu.be/hdSrT4yjS1g
- grumblestumble 10y agoCame here to recommend Stormpath, too. I don't actually use their API but the docs are amazing and some of their presentations on REST API design are phenomenal.
- wraith69 10y agoI use the FDA's 18f API and the Jsend standard.
- niftich 10y agoThe 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
- einrealist 10y agoRoy Fieldings dissertation. If a client starts to construct URIs, then there is a flaw.
- SilasX 10y agoSo every accessible URI must be explicitly presented to the client? Even when there are trillions of possible combinations of settings?
- einrealist 10y agoDoes your browser need all the ressources of the Internet at once?
- SilasX 10y agoNo; 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 10y agoYou 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 10y agoInferring 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".
- icco 10y agoFlickr still has one of my favorite APIs: https://www.flickr.com/services/api/ https://www.flickr.com/services/api/
- BinaryMachine 10y agoJSON API! http://jsonapi.org/ http://jsonapi.org/
- jgalt212 10y agoThe Bloomberg OpenFIGI API is very clean. https://www.openfigi.com/api https://www.openfigi.com/api
- kwikiel 10y agoAnything scaffolded by rails.
- rimantas 10y agoIn 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 10y agoHATEOAS. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte.... I read this and still have no clue!
- Shicholas 10y agoJsonapi.org I feel this embodies every trope of building web apps (well at least ones that use HTTP 1.1)
- spencera 10y agoI also find GitHub to be a great example for API design inspiration
- programmarchy 10y agozettajs [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."
- taf2 10y agoTwilio - 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 10y agoTwilio is one of the worst. The documentation leaves out crucial details some of the time and an XML interface for phone calls? Gross.
- coroutines 10y agoI'm actually using the responses here as a hunting ground for companies I'd like to work for. Carry on...
- hoodoof 10y agoSometimes 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
- hoodoof 10y agoQuestion: to what extent does it really matter that an API closely meet the REST best practices?
- thesimpsons1022 10y agoi can tell you a bad one: Yammer
- Yhippa 10y agoWashington Metropolitan Area Transit Authority API: https://developer.wmata.com/docs/services https://developer.wmata.com/docs/services
- digitalpacman 10y agoGithub
- shravvmehtaa 10y agohttps://lob.com/docs https://lob.com/docs. I'm an engineer at Lob. We'd love any feedback! support@lob.com.
- fapjacks 10y agoYour 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!
- davidgh 10y agoThe 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.
- KuhlMensch 10y agoYeah. And at very least budget some API dev time to respond as the client design unfolds. A static API, with an frontend app in discovery phase is a sad state of affairs.
- LeicaLatte 10y agoif you are looking for data aggregated around time wakatime has a good take - https://wakatime.com/developers https://wakatime.com/developers
- loadfocus 10y agohttps://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
- bjourne 10y agoI'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 10y agoThat 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
- junto 10y agoI was quite impressed by the Rackspace API: http://api.rackspace.com http://api.rackspace.com
- tvvocold 10y agoCheck this if you know Chinese: https://open.coding.net https://open.coding.net
- AhtiK 10y agoPostgREST 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/
- perseusprime11 10y agoBased on the comments, this thread can also serve as your go-to example for the worst REST API...
- aaronhoffman 10y agoAny OData love? http://www.odata.org/ http://www.odata.org/
- herbst 10y agoTwitter v1 was amazingly simple and well documented.
- westoque 10y agoCoinbase. 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
- claudinho 10y agoSmart2Pay has a pretty neat REST API documentation. https://docs.smart2pay.com/category/getting-started/ https://docs.smart2pay.com/category/getting-started/
- deleted 10y ago[deleted]