PHP Based API Development

[bhikkhu]

I am starting development on a new project, and as I have learned from past mistakes, I'm trying to anticipate and plan for a few features in the future.

 

The one I am struggling with the most is the concept of having an API into the data and features of the site. I searched around the forums here and, unfortunately, most of the search results tend to return questions and solutions on using specific API's. I apologize if another thread exists, please point me in that direction.

 

Long term goal: Have a fully featured API that would allow other developers to access, and even manipulate data from an external source outside of the site itself.

 

Short Term goal: Write the base system with the long term goal in mind so that it's easy to implement when the time comes.

 

Of course I'm not expecting anyone to tell me exactly how to do these things or provide any code examples... i am simply looking for resources. I am shocked and amazed at how difficult it has been to find anything in the form of a website/tutorial/book related to this topic. I am sure somebody out there has had some recent experience in this and I would greatly appreciate your sharing of the resources you used.

 

Thanks in advance.

[Buyocat]

Well I'm not sure whether the presentation/powerpoint I'm thinking of is available online, but you should try searching for Java collections API or something like that.  The person responsible for the collection API talks about what common things are important to API design.  I remember some of the points so I'll share them.

 

1. Make it easy to read

That means make the method names short when possible and clear.  Do not use abbreviations.  So if you want to make a method getSrc you should probably just call it getSource instead.  Only use abbreviations or acronyms when they are very well known.  For instance it may be ok to have a method db_connect instead of database_connect.

 

2. Keep the parameter count low

This is just good sense anyway, but try to keep the number of parameters as low as possible.  When I say low I mean between 0 and 5 let's say.  Avoid using parameters with default values because those will become confusing for those attempting to learn your API.  Also avoid making methods which do some "magic".  For instance instead of having the method hide() and reveal() you might just make show(boolean yes).  I think with that example you could go either way, but the point is be explicit.

 

3. Try to avoid throwing exceptions

You don't know whether the end user will user exceptions for control flow or another approach, so don't force exceptions on him.  Of course you can (maybe should) use exceptions internally but be sure to catch them all and return failure values.

 

4. Make the methods testable

This connects into the last point a little.  Try to avoid having methods which return null or return different sorts of things.  In strongly typed languages this is built in, but in PHP it's tempting to return objects or false.  I think you'll have a better API if your method attempts to return a single type because it will be easier to test and understand.  Void methods hsould be avoided (when sensible) as well because you can't really tell if you succeeded or not.

 

5. You cannot change your API

This is perhaps obvious, but as soon as you publish the API it cannot be changed.  That's why Java for instance has to support all the depreceated methods.  The lesson then is to only add the things you really thing make the API stronger.  You can always add new methods later based on demand or whatever, but you cannot take them away.

 

6. Aim for coherence

Again this may be obvious, but try to keep your API method related.  The more closely related they are the better.

 

That's all I have off the top of my head.  If I remember some more I'll be sure to share it with you, but I hope that helps in the meantime.

[Buyocat]

Another one came to mind,

 

7. Avoid using foreign data types

This means try to keep your return values limited to the basic types i.e. string, int, boolean, array.  Don't make someone use a more complicated data type that you use internally just because you're too lazy to convert it into a primitive type.  By reducing your return values to primitive types you let the user decide how he wants to represent the data, and he has the power to easily build the return value into whatever he wants.

[bhikkhu]

These are excellent, thank you so much.