API design resources

I see plenty of discussion around consuming other’s APIs, but what I am after is some resources covering best practice for API design for my own web application. Topics such as REST versus SOAP, Identity, Authentication, Session control, JSON vs XML etc

Suggestions anyone please?

Hi Snapey,

http://schlitt.info/opensource/blog/0706_identity_map_pattern.html Is a pretty good overview of the identity map pattern (better than I could write ;))

Validation can benefit from a strategy design pattern. Sometime very many validation methods are required for filtering inputted/outputted data, and sometimes only one validator is needed. A good time to employ this pattern is if you are using many case statement in a class then that class is a good candidate to be re-factored into a strategy pattern.

With Authentication may people favour http authentication because of its simplicity; although there are a number of other rolled authentication classes in zend, ezcomponents and other classes that you can make use of.

I wrote my own auth and permission class that work together with a database and hash and salt the user’s login info and validates/creates php session stored in the database against a check if the hash matches. I did this because I wanted a way to set group permissions and could easily validate a group permission to access objects or areas within the application.

Sessions should be stored in the database (if you are using a db as generally it is more secure) and you can easily write or borrow a session wrapper class. One should not try to jam too much info in sessions as they aren’t very efficient with large amounts of data.

Generally people either choose a SOAP implementation or a JSON implementation. JSONP can be used to transport JSON data across domains. Many people prefer JSON data over XML as it is ‘lighter weight’ less cumbersome to prepare than XML data and certainly easier to parse. The Javascript libraries such a JQuery and PHP has support for JASON encoding and decoding.

If you want to publish some sort of feed or consumable serialized info you can expose a JSON service that you can publish and others can subscribe to.

The Observer pattern can be used for a publish and subscribe type of functionality. This pattern can be used to provide an API to others, say to write plugins for your App. Another example were an observe is well employed is in a logging class where you might want to have a email fire, a system log written, a screen error to occur and a database log to be inserted. The Observer pattern can be quite powerful in objects being able to share their current state.

Factories are good when wanting to create many instances of something. Combined with a registry you can, for instance, create a single static instance of a db object and then have any object that require db operations can retrieve that instance from the registry.

I personally prefer using a dependency container Ren (a member at sitepoint) and Kyber (wrote Bucket) and LastCraft (wrote Phemento) (sorry about the spelling it may not be correct :rolleyes:). These are all containers that you can use to service your object dependencies. I like to wrap my classes that use db operations in a bucket so that my db and other class dependencies are automatically fulfilled. (I use Bucket)

There is a many other patterns that you can use to service the different functionality, of your application. Martin Fowler and group of 4 people (Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides, known as “the Gang of Four” – they coined the first published 23 design patterns) have great info on patterns and Martin Fowler really helps you understand refactoring.

I don’t know if these small interjections help but I hope so.


Basically building your own API is almost the same as building a website. You process request, authenticate it if necessary and return result in structured data format like xml or json. You would also make use of Http response headers and Http response codes.

Oauth authentication is pretty good for API, I recommend you install pecl oauth extension, it has the necessary functions to act as Oauth provider as well as Oauth consumer.

Thanks Steve. There is a lot of good information here.