I have to create an API for our application that is accessible over HTTP. I envision the API's responses to be simple XML documents. It won't be a REST API (not in the strict sense of REST).

I am fairly new to this space - of course I've had to consume some Web API's in my work, but often they are already wrapped in language native libraries (i.e., TweetSharp).

I'm looking for information to guide the design of an API. Are there any articles, blog posts, etc. that review and expound upon the design choices to be made in a Web API?

Design choices would be things like how to authenticate, URL structure, when users submit should the URL they POST to determine the action being performed or should all requests go to a common URL and some part of the POST'd data is responsible for routing to a command, should all responses have the same document root or should errors have a different root, etc., etc.

Ideally, such articles or blog posts would enumerate through the common variations for any given point of design and expound on the advantages and disadvantages, such that they would inform me to make my own decision (as opposed to articles that simply explain one single way to do something).

Does anyone have any links or wisdom they can share?

  • Or is this better on StackOverflow? (can hardly decide these days) Commented Jan 14, 2011 at 0:05
  • This is a very open-ended question which is hard to answer. Could you make it more specific? Commented Jan 14, 2011 at 23:41
  • @Martin: "Does anyone have any links or wisdom they can share?" It is meant to be in a way open-ended. I am in a research phase, looking for information to take in. There isn't exactly a more specific question yet. Commented Jan 14, 2011 at 23:50

2 Answers 2


Is there a reason to avoid RESTful APIs? The principles make for better web apps, and you can simplify how you implement them in a number of ways:

  1. URIs refer to real things. Things in your domain like Users, Badges, Documents, Videos. URIs don't contain the actions or other instructional bits of the request. These URIs let your applications talk about things apart from their state and verbs (this is good). This concept is good for usability, and is good for the application as it keeps the URI space neat and tidy.

  2. Returned data refers to other system data. Instead of your application magically knowing about where things are, the data returned from each request knows about data related to it (a User.xml packet might include URIs to their ContactMethods, for example). This moves the knowledge of the system from the application to the data, allowing multiple clients to change their implementation when the data does.

  3. Returned data defines the shape used to send data back to the server. If you get an XML record of a particular shape back for a User, that's what the server expects you to send when updating it. You can simplify this principle by using the same keywords, so when receiving XML, you send POST parameters with the same naming structure.

  4. Actions are separate from the data. The ideal HTTP implementation uses HTTP header actions for manipulating the data: POST for updating records, DELETE for deleting them, GET for viewing them, OPTIONS for learning about them, and so on. The ideal is not required (as not all clients can easily send HTTP DELETE messages), but the principle can be simplified into a common set of POST and GET commands (a common set of variables mapped to those actions).

As for authentication, there are a number of common models used:

  • API keys. Your system generates a key to allow 3rd party access. Your system grants access rights using this key.
  • Session authentication. Sessions, via cookies, POST/GET parameters, or otherwise, are initiated, and used for subsequent access to APIs. This requires that clients can store their SESSION (a small number of libraries and platforms require a bit more work to do this). The session may be verified by your site, or by a 3rd party using various mechanisms.
  • Per-API authentication. Each API call requires credentials in some form (as POST parameters, HTTP authentication, etc.)

API keys fit the basic problem of controlling who has access to your APIs (including throttling), and can be useful for providing access to both public and private data, though private data requires additional authentication.

Sessions are the most common authentication, often relying on a 3rd party storing and checking the credentials (as Twitter does, or Google, etc.).

Per-API authentication is the least useful, but can be a valid compromise when the clients or server system require it.

As for the debate on REST versus other approaches, it can be heated, but most often centres around:

Is basic HTTP good enough, or does it need more mojo?

The debate is usually cast as REST versus SOAP, as they make significantly different design choices. REST relies primarily on what exists in HTTP, where SOAP adds the concepts as a layer of descriptive XML. Both are valid approaches, but I have found that REST offers more options for web applications, as it is more open to varied data representations (like JSON, which is especially handy when working in Javascript).

A few choice SOAP versus REST links:

And a few pointers on basic API design:

And if you haven't read it, I strongly recommend reading Ryan Tomayko's How I Explained REST to My Wife (it's funny and informative).


I believe the challenges that you are listing in your question could actually be solved by following the guidelines of REST. This well-thought-out architecture solves many of these problems, such as how to design the API, how to handle security, etc.

The nice thing about REST is that it is an architecture, and you can take what you want from it. It doesn't have to be "strict" but will simply be more RESTful or less RESTful.

Whatever language you are using will also most likely have a framework that makes building REST web services much easier. The advantage of these frameworks is that they will help you make good design decisions as well as avoid reinventing the wheel.

I'll leave it to you to research these REST frameworks for your particular language as I don't know what programming language you're using.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.