Goal
I've been tasked with versioning a pretty large PHP Lithium API.
The end result I'm looking for is to use namespacing to separate the versions.
For example, normally a lithium route that looked like this:
Router::connect('/{:controller}/{:action}/{:id:\d+}');
Could have the following URL, map to the following PHP call:
http://www.fungames.com/game/view/2
app\controllers\Game::View($gameId)
But I would like to create the following mapping:
Router::connect('/{:version}/{:controller}/{:action}/{:id:\d+}');
Such that the following two calls could be made:
http://www.fungames.com/v1/game/view/2
app\controllers\v1\Game::View($gameId)
http://www.fungames.com/v2/game/view/2
app\controllers\v2\Game::View($gameId)
Problem
Unfortunately, the Lithium documentation doesn't make much mention of API versioning. There's a brief mention here as an example of continuation routes. But that approach would required making if statements in my controllers to version my API, and I personally consider that a poor approach.
TLDR
What is the best way to achieved namespaced API versioning when using the PHP Lithium Framework?
API versioning is a really broad topic, and while Li3 gives you all the necessary tools to implement any approach you choose, the actual implementation is up to you. Having said that, the routing layer is fairly sophisticated and will get you very, very far. See this gist on routing configuration examples.
Combining this with Request::get() which allows you to match on any request parameters including headers (you can pass get()-compatible values as $params in Router::connect() — see examples here),
and Request::detect(), which allows you to implement custom matching logic, you can send any configuration of values down to the controller/dispatch layer. This allows you to segment your versions by differently namespaced controllers (with fallback to the default), prefixed actions, or pass a namespace/class path for a different model.
Yet another approach, and one that I would recommend in the general case, is implementing a set of transaction managers/mappers for any endpoints that need to be versioned, and using them as an intermediary between your controller and your model, then use routing to switch between them.
This approach is made easier if you evolve your API using, i.e. content types, since you can choose a mapper based on that. This is also nice since version numbers are strongly discouraged by REST's creator.
Anyway, hope that helps.
Related
I have been glancing at a RESTful specification available on http://restfulobjects.org (direct link to spec here). It is a little different from other things I have seen, but it makes sense, and having examples and clear specifications makes my development a lot simpler.
According to the standard, the URIs will be like:
api.example.com/object/user/31
api.example.com/object/user/31/properties/username
api.example.com/object/user/31/collections/channels
api.example.com/object/user/31/actions/someFunction
api.example.com/object/user/31/actions/someFunction/invoke
See this answer for a brief explanation of the structure. It is quite clear.
Note: This is not a discussion whether or not services/actions can be
represented as resources. There is a good discussion on that topic
here: http://www.infoq.com/articles/Intro_Restful_Objects. Look towards the end of the comments section.
My project is still on the drawing board, and most design elements up for grasp. I will however be using Symfony. I have my entities, and I have some services that act on those entities, and I have controllers to define what the services will do in a specific context.
And so to my actual questions:
...the Restful Objects spec is not based on the MVC pattern - it makes
no assumptions about the architecture of the server that implements
the API. In the URL:
~/objects/customers/31/actions/lastOrder/invoke
the 'actions/lastOrder' is not specifying a controller action, it is
specifying an action (i.e. a method) on a domain object (customers/31)
How do I structure my controllers in the most efficient way if I want to use the specification in an MVC application? Considering that the controllers would somehow serve different resources (objects, services, domain-types) as well as different representations of that resource. What are my layers?
Update Do I have e.g. a customer controller? An generic object controller? A useraction controller?
Do I need to rethink my whole entity/services approach? i.e. the solution for how to implement this is beyond the controller structure? (I fear it is, and then I do not know my next step)
For simplicity/efficiency I would like to make use of the FOSRestBundle and NelmioAPiDocBundle. I believe this can be done, but I then am concerned the spec will only serve as a url template for me, and not being implemented in my logic/design since I have to massage my framework to fit the URL somehow.
Please excuse my ignorance if this question has an obvious answer. I am new to RESTful APIs. If it comes down to a subjective perspective on implementation model, please give me some pointers, because I am currently at a loss for how to approach this.
From the "What is Symfony2 ?" article of Fabien Potencier:
Is Symfony2 an MVC framework?
If you look around, every single framework seems to implement the MVC pattern. And most of them are advertised as MVC frameworks... but not Symfony2. Have a look at the documentation, and you will see that the MVC pattern is only mentioned once or twice, but Symfony2 is never defined as being an MVC framework.
A bit later in this post:
Symfony2 is an HTTP framework; it is a Request/Response framework.
That's the big deal. The fundamental principles of Symfony2 are centered around the HTTP specification.
...
Sometimes, you just need a way to create a REST API. Sometimes, the logic is mostly in the browser and the server is just used to serve data (think backbone.js for instance). And for these projects, you don't need an MVC framework. You need something that handles a Request and returns a Response. You need a framework that implements the HTTP specification. HTTP streaming is yet another example that does not fit well with the MVC pattern.
...
And if you like to call Symfony2 an MVC framework, then you should know that Symfony2 is really about providing the tools for the Controller part, the View part, but not the Model part. It's up to you to create your model by hand or use any other tool, like an ORM.
As Symfony is a set of components, you can easily adapt your usage of the framework to the project you are working on, and the principles that you want to follow (here a REST specification).
The FOSRestBundle is very extensible.
You can define your routes manually, create different views of your objects through serialization.
Plus, I think you can keep very light controllers by writing the most of your objects management's logic inside Repository classes.
So,
Use simplified models and serialization to have different views/layers of your objects.
You should not rethink your whole Entity/Services in order to be more REST, just give them some changes/improvements in order to use them through data-transfer objects/domain objects (models) and Repository classes (fetching/storing methods).
You should be able to take benefits of use REST utilities such as FOSRestBundle, it provides more than built-in actions, allows you to make all custom stuff that you could need, be MVC or not, and be REST or not. It's at your own appreciation.
Have you considered using either Naked Objects (for the .NET platform) or Apache Isis (for the Java platform)? Both of these give you a complete Restful Objects compliant restful API for free - derived entirely from your entity models. (I am responsible for the first of these two. Our implementation is built on top of the ASP.NET WebApi framework. We have a RestfulObjectsController, with many methods on it, but these are all generic methods, corresponding to the various Restful Objects resource types - we do not need to add any new methods specific to the domain objects or their actions.
I'm somewhat familiar with using the Amazon MWS apis, but I'm new to CodeIgniter and the whole hmvc thing. I'm curious how I would add the api into CodeIgniter. Would I have to dissect the entire api into the appropriate mvc folders, or could I just add it as a library. If the latter is the case, how would I use the api?
I'm sorry if this is vague, but I would greatly appreciate any help you're willing to offer! Thanks
I cannot say anthing specific to CodeIgniter, but I've worked with various MVC libraries, so I can give a general overview. Your options are:
I) Write a model from scratch
New code accessing the MWS would mostly end up in the "Model" space. The controllers and views (which you'll probably eventually need) are outside the scope of the code that Amazon provides, so they need to be written anyways. As far as the MVC (and OOP) idea goes, this is the "proper" way to do it, you can make full use of inheritance and polymorphism.
Advantages: Your model accessing the MWS will follow the rules and guidelines of your MVC framework. It will be easy to integrate into other parts of the framework, and integrate nicely with the rest of the code.
Disadvantages: lots of code to write and (more importantly, since MWS is a moving target) maintain.
II) Use Amazon's code as a library
Amazon's code would go into the "Libraries" space. As it doesn't follow the rules of your MVC framework, it will "feel" foreign to the rest of the code.
Advantages: Less code to write and maintain.
Disadvantages: No usage of the framework, no code reuse, no inheritance and no polymorphism.
III) Write a wrapper
This is basically a mix of the two options above. You write a very thin wrapper around the library (goes into the Model space) which calls the unmodified Amazon library. Written properly, you might get a "best of both worlds" - this depends on how much the interface the library matches your desired model interface.
Advantages: Often only little extra code is needed, when compared to the "library" approach", while the model can be used in the same way as a complete rewrite.
Disadvantages: Sometimes needs almost as much code as writing from scratch.
Suggestions and Comments
My approach would probably be to go with a wrapper, unless I need just a fraction of the library's code. Since PHP does not have a strict object hierarchy, it is usually possibly to properly mimic inheritance anyways if needed.
A side note on designing a model around the MWS: Unlike most web services, some calls to the MWS API (e.g. SubmitFeed) work asynchronously in that information about the success or failure of an operation will only be available minutes (or even hours) after the call has been made. Most MVC model hierarchies and interfaces are not designed to handle that type of thing well, so a complete rewrite might not give you the benefits that you'd normally get.
Please remember, that I have no knowledge about CodeIgniter. Your mileage may vary.
My solution is specifically for the Yii PHP Framework but principle should work modifed for Codeigniter external library autoloader:
Put the entire Amazon MWS PHP SDK into your Vendors folder or into an Extensions folder or whatever CI prefers for external libraries. You might have to create that folder and refer to it within CI
Then find out how to use CI's autoloader so it autoloads the library from step 1 above.
Then just call whatever part of the Amazon MWS library from step 1 from your controllers.
This is quick reply, so if I've missed something let me know so I can edit.
For more in-depth discussion visit below to see how we overcame this along with exact code we used for the autoloader and other things dealing with the Amazon MWS PHP SDK
http://www.jescor.com/amazon-price-update-program/
I am a beginner with PHP but I know most of the basics. I currently have an API for my website, coded myself, of which I can call different methods with different parameters and they will scour my databases for the relevant information.
However I want to convert it to REST.
So instead of having requests like this http://mywebsite.com/api/?param=allPosts I would have something like http://mywebsite.com/api/posts/. I would do this for each of my 23 different params.
How could I do this?
One way would be to use a micro framework for routing. This would 'point' url request patterns to relevant php files (controllers) to manage those requests and serve content (or perform CRUD operations, or whatever it is your API does).
There's a good post here with some discussion and further links.
https://stackoverflow.com/questions/115629/simplest-php-routing-framework
I'm currently in the process of using the framework Silex for this exact purpose
http://silex-project.org/
It may be that you wish to convert your PHP application to use one of the many frameworks out there (which will handle routing amongst other things).
The usual suspects are
CakePHP
Codeigniter
Symfony
Lithium
and there are many more...
This is not strictly speaking RESTful that is just prettifying your URL's.
To "Prettify" your URL's you could implement something like this:
Trim your base URL of the start of the request
explode the remaining string by the "/" component
The first component (normally) is related to your controller
The next component is your action in this case equivalent to how your using ?param=allPosts
RESTful routing is based around the idea of using the different HTTP verbs (GET/POST/PUT/DELETE) to decide what actions to take on your resources on the server. Wikipedia has a good overview.
One way would be to use apache's mod_rewrite to effectively convert the second type of request to the first. It's not necessarily ideal, but it's a pretty straightforward solution to your problem.
My team have to maintain a large php application that was very poorly written. It is a mix of html, javascript and SQL on top of a large poorly designed database (ex. it has a table with few hundreds of columns). The only advantage of the codebase is that it works.
We are constantly bug fixing and rewriting parts of it.
I would like to give a structure to the rewrites we do, so I've though about integrating an mvc framework in to the codebase. Could you suggest any good framework for environment?
Here is a list of things that the I would expect from such framework:
The API must be very stable. We can't afford to rewrite the code on each release.
Custom session management or at least working on standard $_SESSION[] (To be able to talk with old code).
Custom authentication.
Using the raw SQL should be well supported (The database is hard to represent in terms of objects).
It shouldn't assume that I will have a table per controller.
I suggest Zend Framework for this purpose because it is a glue framework. With ZF you are not forced into the harness of how the framework expects you to work with it. You can pick what you want and gradually replace your legacy code with code from ZF. It also supports all the things you mentioned.
In addition, I suggest to run the various QA Tools found at phpqatools.org to support you in debugging and refactoring.
Framework comparisons
http://www.phpframeworks.com/
http://php-frameworks.net/
I'm echoing Zend just to list how it fits your specific requirements:
The API must be very stable. We can't afford to rewrite the code on each release.
As mentioned, the API tends to be stable between minor releases. Major releases with changes shouldn't be hard to integrate.
Custom session management or at least working on standard $_SESSION[] (To be able to talk with old code).
Zend_Session does exactly what you want. The default session store is $_SESSION to which Zend adds a namespace concept. Your existing code should be fine, and any new code can use the Zend object to ensure there are no variable name overlaps.
Custom authentication.
Zend_Auth has a few authentication backends, but it is designed to allow you to implement your own auth.
Using the raw SQL should be well supported (The database is hard to represent in terms of objects).
Zend_DB implements the table gateway pattern which will allow you to access the data via object; however, you can also just use SQL directly and get the results as arrays.
It shouldn't assume that I will have a table per controller.
Zend_Controller and the rest of Zend's MVC implementation make no assumptions about the Model, leaving that completely up to you. I'm sure some people don't like that, but it is the one area of MVC design that varies greatly from project to project - so that's left completely to the developer. You could extend some of the DB classes, or just use the existing DB access code.
That's an example of the pick-and-choose mentality of the Zend Framework. You really can use any of the library by itself. That should work well with your project. For example, you could use Zend_View without the rest of the MVC classes just to move your presentation into templates. Or just use Zend_Auth to replace the existing Auth system. With Zend you can slowly move your project into a more structured state, little by little.
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 ?
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.
Build a set of Facade classes that simplify the public API.
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.
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.