A few tips for Web API design

http://vermorel.com/journal/2010/12/22/a-few-tips-for-web-api-design.html

by p4bl0 • 16 years ago

32 22 16 years ago

pilif3• 16 years ago

The best thing to do would probably to be dogfooding your API from the beginning. To do that, only expose your business logic over your REST API.

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.

RyanMcGreal• 16 years ago

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.

Charuru• 16 years ago

deja vu. I feel like I saw this exact comment before on HN.

I can't find the HN post though.

cmelbye• 16 years ago

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)?

pilif3• 16 years ago

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.

andrewmccall• 16 years ago

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.

wiseleo• 16 years ago

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. :)

udoprog• 16 years ago

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.

wlievens2• 16 years ago

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.

vhackish2• 16 years ago

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).

phpnode2• 16 years ago

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.

mseebach• 16 years ago

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.

ZoFreX• 16 years ago

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!

mccutchen• 16 years ago

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

phpnode2• 16 years ago

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.

vhackish2• 16 years ago

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!)

pak• 16 years ago

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.

A few tips for Web API design

Related Stories