tags:

views:

140

answers:

1

We have developed a B2B Web portal for Graphics Job Work which is similar to Camera Ready Art (www.camerareadyart.com). It is targeted for people wanting to convert bitmap to vector Graphics, Logo Designing and general image processing like coloring B/W images to color,etc.

We want to add facility so that people (our clients) can use a set of API that we provide to post their work from their site directly without having to visit our site literally to post their work.

I have never done anything like this till date so I have no ideas as to how I can implement something like this. I also want to know about how we can implement security so that only those who are authorized can post their work?

Can anyone give me ideas as to how we can do something like this.

+1  A: 

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.

Jon Cram
Thanks for such an informative reply.This means I should implement the API as web service. Because only web service will be able to expose the API and the user will only be able to connect through that.Am I right or there is another way?How will web serveice be made available. Will the Hosting company be required to make any changes on server?
Yogi Yang 007
A web service is probably the best option for a web-based product. No implicit changes would be required of the hosting company. Ideally your app and your api should be on different hosts (different IPs, either logically or physically). Nothing different is required to make the web service available than would be required to make a web site available. The only difference is that a given URL returns not a web page but some machine-oriented response format, such as an XML or JSON indication of the result of the request.
Jon Cram
Jon, Thanks for your valuable input. Now I understand most of what I have to do. BTW the site is already operational the only thing is that it is still not hosted. It is on our company's testing server. We are stress testing it. It was suppose to go operational on 1st Oct 2009 but suddenly our client has asked for this API feature.So it is not the way you have stated (First API and then Development). It is the other way around :). Once again thanks
Yogi Yang 007
If you can, release now without the API explaining to the client the extent to which the release will be delayed due to *correctly* implementing an API. Then build the API and re-work your app so that version 2 sits on top of the API. This is a huge architectural change that will take a long time at this stage in the project. Hopefully your client will understand the extent of the change they are requesting!
Jon Cram
OK I will try to convince my boss to convince our client to launch the site as scheduled and then we will work upon the API part.I hope you will be available in future if we have any problems?
Yogi Yang 007
I'm sure the entirety of stackoverflow.com will be around to help - I can't personally guarantee direct support!
Jon Cram