

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

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

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

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

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

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

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

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

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

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

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

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

