This question covers a very large area and I doubt any single answer could cover matters in detail. What I can do is offer some starting points based on the mistakes I have made.
Build on top of your own API
Don't add-in API features to an existing system. Doing so will:
- lead to additional testing load (you'll have to test both your app and the API independently)
- result in an increase in overall maintenance costs
- result in a poorer quality API than what you want to offer
Your overall goal should be to build the API first and then build your app on top of your own API. Doing so has the following benefits:
- testing of the API is inherently performed whilst testing your app
- you won't 'forget' to add any required API methods
Your app and your application logic (the API) will be logically separated - there will be a clear separation between them in terms of what each side of the equation does and what it is responsible for. This will help guide development. This will also allow you to very very easily put the app and the API on different machines as and when this is needed.
Using your own API is a very important point. The design of your API will initially be sub-optimal and only through using it yourself will you be able to make it offer to people the features that are actually needed in a way that is efficient.
You will end up with a system that roughly looks like this:
------------- -------------
| | | |
| Your APP | <= HTTP communication => | Your API |
| | | |
------------- -------------
This highlights some further benefits: you can replace 'Your APP' with any other app, allowing customers of yours to create apps to deal with things in ways that work with them best. You can also create new versions of your app on top of the existing API - moving to a new version of your public web site can be much easier.
Designing your URLs: mapping to classes and methods
Choosing sensible URLs is as much of a problem as choosing sensible class and method names. Deriving URLs from classes and their methods is a good approach. If there is no sensible correlation between URLs and classes/methods, you will find things harder to maintain in the long run.
I personally prefer to associate URLs to classes and methods in the following ways:
- map classes to top-level directories
- map methods to sub-directories of the top-level directories
Example:
The URL of your API is https://api.camerareadyart.com.
You have an image object with toColour() and toBlackAndWhite() methods.
This may map to:
https://api.camerareadyart.com/image/toColour/
https://api.camerareadyart.com/image/toBlackAndWhite/
Similarly for bitmap to vector conversion:
https://api.camerareadyart.com/bitmap/toVector/
Designing responses
When someone GETs data from, or POSTs data to, one of your URLs, what happens? How are errors handled, how are exceptions dealt with? What form do responses take?
I can't tell you what to do here. Personally I prefer to map things as closely to HTTP as possible and then only go beyond this when needed.
For example, if an incoming request is accepted and is processed but runs into an error internally I would issue a 500 status response. Likewise if a given API method requires authentication that has not been provided I might issue a 403. Taking advantage of existing HTTP features prevents you from having to re-invent certain things.
Use existing aspects of HTTP
As well as using HTTP status codes sensibly, make sure to look around for an HTTP-only method for doing something before rolling your own solution.
Want the user to specify whether the response format should by XML or JSON? Use the HTTP Accept header.
Want to re-direct a client to a different URL to grab the result of a request? Use the HTTP Location header.
There are many features to HTTP that already handle many things you might want to do. Use them!
Security
There are two general problems to tackle here: authenticating the user, and determining what actions a given user can perform.
Security: authentication
The user will need to specify in their request who they are.
The first solution to spring to mind is to allow the user to specify a username and password, possibly the same as the username and password they use to access your app. This seems on the surface to be a good idea but it is not ideal.
Users will end up baking their username and password into their own apps. Inevitably one user will forget their password and will change it so that they can happily access your app, breaking their own app in the process.
A better choice would be for the user to supply an authentication token, which is essentially a single value unique to a user much like a username and password rolled into one.
This allows you to logically separate a username and password from access to the API. A user can change their username and/or password for your app as often as they like without breaking their access to the API.
A user can also have multiple API tokens, each with different levels of access, allowing a user to safely give out an API token to a third-party service.
Security: access control
As far as the outside world is concerned, your API is a set of URLs. Each URL is, by definition, unique and performs a unique task. Basing your access control mechanisms around these concepts is a good starting point.
I prefer to keep a list, per token, of the URLs that token is permitted to access. When a given token is used to access a URL it is trivial to tell which URL is being accessed and whether it is in the token's list of allowed URLs.
If you choose a set of URLs wisely, where each URL performs one unique action, this process provides you with about the finest level of access control as you're going to get.
To give a finer level of control you may also want to specify, per URL that a token is allowed to access, what query arguments they are allowed to use.