Building a Simple API with ExpressionEngine Templates

UPDATE 1: This article has generated a lot of discussion since it was first published and I just want to reiterate as is stated in the footer that this is not the best way to build an API with Expressionengine. To do that you would build an add-on that could also handle put, post and delete operations. This article is meant only to indroduce the concept of API's and how ExpressionEngine templates can be used to supply the data for them.

UPDATE 2: I have renamed this article. The original title was "Building a RESTful API with ExpressionEngine Templates", however the API described here is not truly RESTful. Thanks to everyone who gave feedback and took part in conversations about this.
 

API’s are one of the things I love most about the internet. Basically they allow you to create a web app that will communicate with a resource or server and do things for you. And with ExpressionEngine templates it is really easy to create a simple API.

ExpressionEngine templates make outputting content very simple and flexible and for the purpose of this article we will focus on the {exp:channel:entries} tag and build our API on the idea that our website has an "articles" channel that we want to make available to other services. We start by creating a basic template that outputs all entries in our articles channel:

{exp:channel:entries channel="articles" dynamic="no"}
	{title}
{/exp:channel:entries}

Let’s assume that this is the "articles" template in a template group called "api". To access it we simply navigate to the domain name followed by "api/articles":
http://www.domain-name.com/api/articles

We now use segments starting with the third segment to define some optional parameters:

Segment 3 = limit
Segment 4 = offset
Segment 5 = display order

And add those to our template tags:

{exp:channel:entries channel="articles" dynamic="no"}
	limit="{segment_3}"
	offset="{segment_4}"
	orderby="{segment_5}"
}
	{title}
{/exp:channel:entries}

Now navigating to http://www.domain-name.com/api/articles/3/1/date will output the 3 latest articles offset by 1. The segments are optional as the channel module will ignore parameters that are left blank, so http://www.domain-name.com/api/articles/10 will simply output the 10 latest articles.

Next we want to output the titles of the articles in a way that is computer readable. We could do this in several ways such as with XML, YAML and JSON. I find JSON to be the most human-readable and user-friendly so will use it in this case. All we need to do is create a list of article titles formatted as follows:

[
	{ "title" : "My First Article" },
	{ "title" : "My Second Article" },
	...
]

And we can easily do this in our template as follows:

[
{exp:channel:entries channel="articles" backspace="1" dynamic="no" 
	limit="{segment_3}" 
	offset="{segment_4}" 
	orderby="{segment_5}"
}
	{ "title" : "{title}" },
{/exp:channel:entries}
]

The backspace parameter ensures that we don’t have a trailing comma on the end that will break our JSON format.

Navigating to the template now gives us the output in JSON format (you can validate it using JSONLint). Congratulations, you’ve just built an API!!

Let’s create another template called "article" which will get a specific article with the following parameter:

Segment 3 = entry id or url title

And create the template:

[
{exp:channel:entries channel="articles" limit="1"}
	{ "title" : "{title}" }
{/exp:channel:entries}
]

Note that because we have not set dynamic to "no" we don’t even need to provide the channel module with any special parameters as by default it is expecting segment_3 to be either the entry id or the url title, and if it is left blank then the latest entry will be shown. So both of these will return the same thing:
http://www.domain-name.com/api/article/85
http://www.domain-name.com/api/article/my_entry_url_title_with_id_85

 

Let's create one final template called "author" which will get all of the entries by a specific author:

[
{exp:channel:entries channel="articles" backspace="1" dynamic="no" 
	author_id="{segment_3}" 
}
	{ "title" : "{title}" },
{/exp:channel:entries}
]

So to get all articles by the author with member id 6 we just navigate to:
http://www.domain-name.com/api/author/6

 

As you have probably realised by now extending this API to include more parameters, categories, article text, etc. is really very simple. And this really is an API – a specification intended to be used as an interface by software components to communicate with each other. Granted it is not an ideal way to build an API – for that you would really want to build an add-on – however it very nicely demonstrates how API's work and how EE template tags give us all the tools we need to build one.

Subscribe Via RSS or Email