CODEWITHSUNDEEP
zend-frameworkrest
Komang
Komang

Reputation: 5064

REST Zend Framework, How to routing module based versioning & Api Key

I am building a RESTful API services with ZF 1.10.8 as am newbie its a little bit confusing when dealing with ZF routing.

I need to have versioning, api_key, and response format in url, something like:

/:version/:response_format/:api_key/:controller ... /1.0/json/1234567890/articles/

The version is module based with the latest version as default

How to get this done?

Upvotes: 2

Views: 2257

Answers (2)

lo_fye
lo_fye

Reputation: 6860

Versioning is really not as simple as putting /v1/ in the URI. In fact, that makes the API non-REST.

To do REST properly, every resource (thing the client wants to access) has one and only one URI. The URI stays the same for v1 & v2 & v2; what changes is how you present that resource to the client.

  • How do you know which version they want? They set it as a request header.
  • How do you know which format (json,xml,html,wml,etc) they want it in? They set it as a request header.
  • How do you know which language they want it in? Request header.

The thing to remember is that the URI they are requesting stays the same. Because each resource only has 1 URI, you never want a method name in the URI.

This is bad: - /edit/place/43

Instead, you should use the proper HTTP methods - to create a place, do an HTTP POST to /place - to view place 43, do an HTTP GET to /place/43 - to update place 43, do an HTTP PUT to /place/43 - to delete place 43, do an HTTP DELETE to /place/43

When returning the response to the client, you should also include the URIs of all related bits of data the client might want to retrieve next. One of the principles of REST is that once the client has connected, it can find all the URIs it needs within the API itself. It only needs to know one URI to get into the system, and from that point on, all required URIs are provided in responses. This has the benefit of allowing you to change your URIs at will, since the client should never be paying attention to what they are... just using them as needed (i.e. the client knows what the URI points to, but not where it points).

Lastly, keep in mind that you don't want to be sending success/error markers as xml or json. They should be sent back as HTTP response codes. There's a code for creation, and one for deletion, and one for updating, etc.

Here are some fantastic articles on REST in general, and doing REST with the Zend Framework in particular:

I particularly recommend the article at weierophinney.net, for implementation details.

Upvotes: 4

Tim Gautier
Tim Gautier

Reputation: 30142

This is just an idea, but I would avoid making the code know anything at all about the version. (Other than what its current version number is.) Instead, I would make the /:version/ part of your URI the base in your rewrite scheme.

So instead of the base being something like: "http://www.example.com/"

It would be: "http://www.example.com/1.0/"

In this way you can simply have different branches of your source control on the server separately and your web server can determine which version to route the URI to. Then your code doesn't need any knowledge of how to handle different versions and your code base doesn't get polluted with large switch statements to do different things based on version.

To make it a little safer, you can require requests to contain the version number in the header. Then your code can just check if the version number in the header matches the version number of the code it's being routed to and throw an error if they don't match.

For example: Sending a GET to http://www.example.com/2.0/ with a version number in the header of 1.0 would throw a "wrong version" error. Your code would only need to know that header_version != current_version, so it shouldn't need to change as you release new versions.

Upvotes: 0

Related Questions