A few tips for Web API design(vermorel.com)
vermorel.com
A few tips for Web API design
http://vermorel.com/journal/2010/12/22/a-few-tips-for-web-api-design.html
4 comments
I can't emphasize enough how much I agree with this. Since I started "dogfooding my API", my applications have gotten cleaner and more logical and my APIs have gotten a lot more usable.
deja vu. I feel like I saw this exact comment before on HN.
I can't find the HN post though.
I can't find the HN post though.
http://news.ycombinator.com/item?id=1931799
I found it because I commented on it and had the same deja vu as you did :-)
I found it because I commented on it and had the same deja vu as you did :-)
I too talked about this before: http://news.ycombinator.com/item?id=1882782
I left that comment.
My colleague just wrote up our process: http://news.ycombinator.com/item?id=2032346
My colleague just wrote up our process: http://news.ycombinator.com/item?id=2032346
I want to do this, but I'm not sure how to handle authentication. If you were to do this dogfooding approach in a new application, how would you handle internal authentication (from your frontend) and also how would you handle customer authentication (from their client apps)?
You have multiple options.
If you use SSL, then it might be easiest to just use http authentication, transmitting the users credentials for each request, which is also the only official restful solution (each request should be independent of each other request).
If you don't want to do that, create an endpoint that takes username and password and returns a token which must then be present in each request (maybe even as part of the authorization header).
Or use OAuth.
If you use SSL, then it might be easiest to just use http authentication, transmitting the users credentials for each request, which is also the only official restful solution (each request should be independent of each other request).
If you don't want to do that, create an endpoint that takes username and password and returns a token which must then be present in each request (maybe even as part of the authorization header).
Or use OAuth.
Another option is the use of API keys that are separated into two types -- partners and end-users. The partner API keys would be bound to a particular end-point (e.g., the IP address of the web server) while the end-user API key could be used from anywhere (e.g., from a mobile device).
The OAuth 2 spec addresses some of these points by providing the user-agent flow.
The only place where it falls down some is when it comes to actually creating users. It's fine with one of the other flows because you can authenticate as an application with client credentials.
The only place where it falls down some is when it comes to actually creating users. It's fine with one of the other flows because you can authenticate as an application with client credentials.
We are working on that even though it initially slowed down the development process. It changed my answers when talking to potential partners from "You can embed our widget" to "You can make an API call and either display our widget or manipulate the data we return as JSON however you want."
Guess which answer is getting me a lot more interest. :)
Guess which answer is getting me a lot more interest. :)
Also, unless you have a very good reason for doing otherwise, please include a JSON version of your API. JSON libraries are just about ubiquitous and it causes far, far less pain than SOAP.
I think you mean XML instead of SOAP. A JSON version of a SOAP service would be a completely different API.
Except for consuming the API directly in a browser, there's little reason that XML should cause you pain.
Except for consuming the API directly in a browser, there's little reason that XML should cause you pain.
> Except for consuming the API directly in a browser, there's little reason that XML should cause you pain.
I disagree. Unless the data I'm working with are awkward/difficult to represent in JSON (ie, they're highly structured documents, for which XML is ideal), XML is always more painful to work with. More painful to produce and to consume.
This is working primarily with Python and Javascript.
I disagree. Unless the data I'm working with are awkward/difficult to represent in JSON (ie, they're highly structured documents, for which XML is ideal), XML is always more painful to work with. More painful to produce and to consume.
This is working primarily with Python and Javascript.
I can echo this for working on iOS with Cocoa touch as well. While there's no native JSON provided by Cocoa touch, there are excellent third-party tools.
XML in iOS is a beast, and a real pain to read (and I've never attempted to write it).
Plus, on mobile devices especially, XML is slower to download because it is more verbose than the equivalent JSON object.
So I agree, unless you need a highly structured document, I always go with JSON over XML.
XML in iOS is a beast, and a real pain to read (and I've never attempted to write it).
Plus, on mobile devices especially, XML is slower to download because it is more verbose than the equivalent JSON object.
So I agree, unless you need a highly structured document, I always go with JSON over XML.
The only applications I've made that interface with JSON or XML APIs were in Java, and JSON was less headache every time. GSON makes it trivial to marshall/unmarshall, and I haven't found an equivalent XML library - not for lack of trying!
not really, JSON makes it easy to exchange standard objects and arrays between languages, in PHP it's as simple as:
$json = json_encode($object);
$object = json_decode($json);
I'm sure it's equally easy in other languages, XML is not good in this use case. There's no standard way to do it.
The Article only mentioned it's string restrictions, but I'm still interested in how they formalize and implement their schemas. It's granted that xsd is pretty messy, but exposing a schema like this - or with alternative definition languages - goes a long way in helping client adaption seeing as there are a trillion autopwn validation and binding tools available.
Exactly. I like how you threw binding in there too; I use schema languages (such as XSD) for binding at least as much as for validation. Maybe it's because I program in a statically typed language, but I really apprecicate the value of schema's and related tools - even while acknowledging the schema languages themselves can be messy and imperfect.
I sort of like schema validation, but it makes it a pain to add things to your objects later if clients of your API are depending on that (they will break when you add something).
SOAP is really for client side programmers that can't figure out how to do an HTTP request and parse XML all by themselves. Also the sell is that you can use automation tools to generate your client side code for you, but I found that they do not all behave the same way when dealing with anything mildly complex (like an array of objects for example). Data streams are also a PITA to deal with in SOAP, there's really no good provision for it. So do yourself a favor and wash your hands of SOAP (ha ha!)
No, SOAP is for businesses that need a clear data contract in place when doing inter-business data integration with real money on the table. That's why it's been used in business APIs for nearly a decade. REST has nothing that parallels the functionality of a WSDL and all the tooling that has been built up around WSDLs. Without a WSDL, you don't have a computer-interpretable spec for the presented API, you have a bunch of human readable documentation, and REST has a huge gap between principles imposed by the philosophy and the protocol that allows for a wide variety in how APIs are designed. I don't think you understand the whole code auto-generation thing; SOAP can't generate much of the client-side code. It might generate the function signatures or an object that has the methods presented by the API. On the server-side, you can usually auto-generate a WSDL from a class definition or vice versa, which is a handy way to start turning that data contract into an implementation.
SOAP isn't going anywhere in the big-business world, but for smaller businesses/apps that can play faster and looser with data integration, I absolutely agree that REST is a simpler and more pleasant choice to work with.
SOAP isn't going anywhere in the big-business world, but for smaller businesses/apps that can play faster and looser with data integration, I absolutely agree that REST is a simpler and more pleasant choice to work with.
Then make your website use that API and nothing else.
That way you are reasonably sure that the API scales, has enough features and is convenient to work with.