Best practices for an API in PHP : functions, or classes ?

Question

Hi,

In my company we have developped some applications. We have to create an API for one application (say application A), so that the others can use it (an its data).

The question is : we already have developped PHP classes for the model of Application A, if we want to create an API, should we :
- re-use these classes (too much functionnalities for an API, too heavy...)
- create one PHP class, with some basic functions, that takes in input and returns only raw values (like strings, array... NOT complex classes)
- create another set of PHP classes, simpler, and designed only to be used by an external application (so only to get data easily)

Usually, an API is the 2nd solution (to be used as well with PHP than as a web service for example), but i find it too bad that we made a complex and usefull class modelisation, then we tear it apart just to have functions, strings and array. The 3rd one seems to me to be the compromise, but a collegue of mine insist that this is not an API. Too bad...

What do you think ?

Answer 1

Build a set of Facade classes that simplify the public API.

Answer 2

Solution number 3 might be the best one from an architectural point of view. Basically you are using a Facade Design Pattern to simplify your API. Since I am dealing with it at the moment: In Patterns Of Enterprise Application Architecture this approach is described as the service layer which makes totally sense since you don't want to expose any user (meaning whoever will deal with your API) to more complexity than is actually needed or desired.

This includes using the easiest possible interface and transfer objects (raw values if they make sense). As soon as your Facade is being called through remoting services (like a webservice) you will eventually have to break repsonses and requests down to raw values (data containers) anyway.

Answer 3

Create some thin wrappers that implement simpler API over the original classes. DO NOT reimplement any business logic in the wrapper - that'd lead you into trouble if any of the logic changes, as you will surely lose track of which piece was modified and which was not. Keep the external inputs/outputs simple, if you need something more complex than string, use XML or JSON for structured data, but try to avoid too much complexity - if you have 2 things to pass two query parameters might be much better than one structure with 2 fields.

That's the 'Facade' pattern.

Answer 4

I would also say have a look at the Facade pattern. Build a set of Facade classes that only offers the functionality that is really needed to be public. Those classes then for sure use your current core classes.

This gives you also the advantage that if you change the core classes, the API must not necessarily being changed.