Create APIs with FRAPI

October 19, 2010

Uncategorized

Imagine: You are working on a large system. It has a substantial and well established code-base, an elaborate ACL system and a lot of proprietary code. You have been asked to create a RESTful API to allow access to all the great features of your application. Of course there are a few options; you could write the code yourself to handle all the new API functionality, or you could use an existing framework that handles most of this for you. When starting to look at creating a RESTful API for web2project I came across FRAPI and loved what I saw.

FRAPI is a PHP-based framework for creating RESTful APIs. Like most frameworks it helps you rapidly create your application by generating skeleton code as well as handling the basic functionality so you don't spend your time re-inventing the wheel. FRAPI, unlike most general purpose frameworks, is not made for building web applications. It focuses on building REST Web Services that developers mashup in their web applications.

The FRAPI admin interface allows you to easily create actions, define error/response codes, create API partners, edit other general settings such as a database connection and last but definitely not least – a nice interface for testing all your actions. Do not mistake "Actions" with XML-RPC like calls. Actions is only a name, common to many developers, used to define resources or collections.

Creating an action via the admin interface is as simple as defining the name of the action, whether it is enabled, public, has a custom route and a description of the action and you can then add parameters for the action. Once you have defined your action FRAPI will generate a PHP class for you with methods for handling GET, POST, PUT, DELETE and HEAD requests. All that is left for you to do is put the appropriate code for your application in each of these methods.

Returning data from these methods is as easy as building an array and assigning it to a class property. FRAPI will then automagically handle converting it to CLI, HTML, JSON, PHP, PRINTR (great when debugging) and XML for output. Most of the time FRAPI will do the conversion perfectly, but for the times it does not you can define custom templates for the output. One example of when you will need to create a custom template is when you have numeric keys in your data array and are trying to output XML. Since a number is not a valid XML tag you will have to create a custom template to handle looping to properly output the data. The templates are PHP-based and simple to create. You just need to create a template file with the same name as your action and put the XML or HTML in it. You can use PHP to access the data from your action and to create loops and other control structures as necessary.

The next important thing when creating an API is defining and documenting your response codes. The FRAPI admin interface allows you to create your response codes by simply defining an HTTP code, error name, error message and description for the response code. Once defined you can easily return the appropriate response code by throwing a Frapi_Error with the a defined error name and FRAPI takes care of the rest.

On top of generating the code for actions and response codes FRAPI will also generate the ever-important documentation for your API in markdown, html, text or pdf formats.

Once you have created your actions and defined your response codes you will want to test them. FRAPI has an admin interface to do exactly that. The interface allows you to select your action, add any parameters, choose your HTTP method and response type and load a specific partners information, if necessary before making the request. Once the request is made the admin interface will display the full URL it used for the request, the response code, response headers and of course the body of the response. This will give you a good overview of the response your action produced and is very useful for debugging when first getting your API set up.

After you have completed creating your API and are ready to move to production you will need to consider scalability. FRAPI can also help out with this as it has caching built in. By default it will use APC to cache as much as it can. However you also have the choice of memcache, memcached, Redis, WinCache and if you do not have any of those a dummy cache is available that lets you run FRAPI without caching.

Now that you know what FRAPI can do for you, lets discuss what you have to do to use it.

All code generated for your actions, response codes and settings is stored under a single directory. When creating the web2project API I created a new git repository and store only this directory. Since we already had an autoload function as well as an ACL defined in web2project, I utilized the FRAPI-created AllFiles.php file which is used for processing all actions. Next, I defined the root directory of my web2project install and included our autoload function and other files that the system required to function. Once that was complete, I could code in FRAPI just as if I were in web2project itself.

If you have a project coming up that requires an API or are just interested in API development in general I would definitely suggest you head over to getfrapi.com and download a copy to try it out yourself. Better yet, grab the ready to go Amazon AMI, load it up and start developing. Of course if you run into any problems or have questions, jump on the irc channel #frapi on Freenode to get some ever-friendly help.

Comments are closed.