Building a custom API--needing a logic check.

Question

I am in the planning and early coding stages of writing my first full-fledged API for a large scale we application. I have used several APIs over the years but this is the first time I have been asked to construct something that will allow programmatic interaction on this level.

I have done quite a bit of research looking for best practices and such and have identified what I THINK will offer a fairly flexible response communication system.

My questions are:

Is this what you expect to see as API interaction?

Did I miss anything important?

Explanation of API:

I am going to be using HTTP Type 1 protocol for communication and a unique API key for authentication.

I am expecting this to come through CURL requests over an SSL connection.

Example of Successful (200 OK) XML Response (rate limit request):

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <short_message>Request Complete</short_message>
    <long_message>Rate Limit Status Response</long_message>
    <response_data>
        <rate_limit>40</rate_limit>
        <rate_used>31</rate_used>
    </response_data>
</node>

Example of Failed XML Response (Will be sent under appropriate 400/500 Header);

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <error_code>1201</error_code>
    <short_message>API Error</short_message>
    <long_message>The requested API version (1.5) is invalid</long_message> 
</node>

Additionally I am setting up the error codes to be used in search-able documentation for easing the migraines of other developers. Pass/Fail of request will be given through appropriate HTTP codes--Success (200), bad requests (400), method not found (404), authentication failed (403), etc...

I am also using version based endpoints so that any code changes will not require external code changes.

Finally devs will be able to request all responses in either XML, JSON, or PHP serialized arrays.

The internals of my code are very simple. All data is passed through POST (probably using CURL or some alternative) including a unique API key. That API key is linked to a user in the system which will then allow the internal methods to execute a limited set of functions that are enabled for that specific user.

I am following the API 'Golden Rule'--"Always add, never delete".

So.. what else should I consider and what have I missed?

Answer 1

The XML looks nice. But to say more about the inner Logic we need more Details than just the XML.

Answer 2

The best API you can use as an example is the API your coding in. Use the same naming conventions and casing.

Also, try to build sample applications using your API and you'll quickly discover its shortcomings.

Answer 3

A few things:

1) Putting response headers into different places - HTTP header AND response_code - will definitely cause confusion. Some developers will check it in one place, some in the other. If you want to go with that route, absolutely make sure that the response codes are identical between HTTP headers and the returned XML.

2) Your server does NOT have to return the API version with every response. You're wasting bits on the wire. If the client wants a specific version of the API, have them send it up in the request. You don't have to send it back to them.

3) Combine response_code and request_status. Look at how HTTP does it: 200-299 means success. 400-499 means client is dumb. 500-599 means server is screwed up.

Answer 4

Have you considered using versioned endpoints? They may require a bit more planning and maintenance on your part, but your users will love not having to rewrite their code every time you decide to change parameters / return values.

If you come up with a plan to deprecate and then remove old versions, this shouldn't prove too painful.

Answer 5

Shane,

I am assuming your goal is to build a RESTful API - is that true?

My answer applies only if this assumption is true - I am not trying to criticize your design, just its RESTfulness.

REST defines 4 interface constraints which your design must adhere to in order to be RESTful. Your design violates at least three of them and hence is not RESTful. This is not necessarily a bad thing in itself but it is important that you understand that your system will probably not have the properties you expect it to have.

I'll try to get you started with a short answer below, but please have a look at http://nordsc.com/ext/classification_of_http_based_apis.html where I discuss this issue a bit more. You can then probably break all this down to smaller questions and come back here or visit rest-discuss on Yahoo groups: http://tech.groups.yahoo.com/group/rest-discuss/

Now short comments to your design:

1. You should not use your own response codes but only use the ones provided by HTTP. You could make up your own ones, but those must be generally applicable and not be specific to your application or interaction.

2. You should use a specific media type, not only application/xml. If none of the existing types match your need (or can be extended to do so), you can develop your own. In fact, the major design activity should be spend on the media type. It is where your domain semantics live.

3. You must adhere to the hypermedia constraint to be truly RESTful. This means that the client should be provided with links and/or forms to discover what it can do next.

Using the classification referenced above, you API seems like a HTTP-based Type I ( http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one ) assuming you do not put actions in your URIs, which would make it RPC URI-Tunneling ( http://nordsc.com/ext/classification_of_http_based_apis.html#uri-rpc )

I hope that helps you with your overall goal.

Jan

Answer 6

If you're really building REST services, consider this:

• request_status, should be drop in favor of html response code (at least 200: OK, 400: Bad Request, 401: Unauthorized, 403: Forbidden and 500: Internal Error), response_code may be needed to find in your documentation an explanation of the problem.
• You want to provide different format, the format of the response should not depend of the url but of the Accept header

Answer 7

About you "single URL/endpoint" idea - keep in mind that with Apache you can serve a potentially unlimited number of URLs from a single script via URL rewriting rules. This means that with a properly defined .htaccess file in the directory of your "endpoint" script you can have your web server automatically "map" incoming requests like this, for example:

/foo/slice/1234 => /foo/?action=slice&oid=1234
/foo/dice/3456  => /foo/?action=dice&oid=3456
/foo/chop/4567  => /foo/?action=chop&oid=4567

This can be very helpful if you decide that you want to serve "RESTful" URLs after all (and can be made to work with HTTP request modes GET, POST, PUT, DELETE, HEAD).