Building a REST API using concrete5 - Part 1
The first in a series of tutorials detailing how to build a REST API on top of your concrete5 website.
APIs are all the rage. Indeed Web 2.0 could be said to be defined by the API and there's no doubt that APIs have played an important role in the proliferation of services such as Twitter: every iPhone or Android Twitter client you've ever used depended on their API.
In the first of these tutorials I want to cover what an API is, discuss why you might want to expose some of your application's data over API, then set out some high level objectives for an API based on concrete5 which we'll then proceed to build.
What is an API?
API stands for 'Application Programming Interface'. Any programming language could sensibly be described as an API, in that it provides an abstraction to the inner workings, or machine code, of the underlying hardware.
However, the term API is most often used in the context of providing external access to an application or resource in a form that allows that application's data to reused or repurposed by another application. More specifically, it's not just a static endpoint which can provide fixed data but instead a system of endpoints that can be queried or posted to, to return dynamic data or perform other operations to interact with the underlying application itself.
A REST API provides for a semantic way of accessing and writing data using a base url, descriptive paths and the standard HTTP methods GET, POST, PUT and DELETE to interact with the application, accepting and returning data in standard web formats such as JSON and XML.
Why? APIs have a number of benefits
- They allow you and others to repurpose data that might otherwise be confined to your application, often in ways you might not have envisaged - think IFTTT.
- Syndication of data can assist in promotion and usage of the underlying application - RSS feeds are a really basic API.
- APIs can break through technical constraints and incompatibilities that might exist between two systems, allowing them to communicate by exchanging data in commonly understood formats such as JSON and XML.
There'll be more. Dive-in in the comments if you think I should add to this list.
Objectives for our API
In no particular order, these are the objectives for our API, and things we'll cover in this and subsequent tutorials:-
- It should be based (broadly) on REST principles.
- It should be versionable. An often cited mantra of API development is that you add but never take away.
- It should support some level of authentication, so that only existing users can access the API. In other words no guest access.
- It should offer both JSON and XML response formats.
There'll be gaps I'm sure, but hopefully at the end of this series you'll be able to implement an API on top of your concrete5 website.
Look out for Part two of this tutorial.