Symphony.

The desire for a RESTful API for Symphony has come up a few times. Most recntly: Plans for web services/API in a future release of Symphony?

While I can’t speak on behalf of the core team with regards to including this in the core in the future. I saw some of Craig’s work of implementing a generic JSON API for the backend, but wanted to see whether native Data Sources and Events could be used instead.

The result: an extension that provides read and write access to Symphony. Essentially it exposes the functionality of a Data Source and an Event, but through a generic, clean URL structure.

http://github.com/nickdunn/rest_api

In short, you can make GET requests to get lists of entries:

/symphony/api/:section
/symphony/api/articles/?include=title,body,date&limit=5&sort=date&order=desc

Or a specific entry:

/symphony/api/:section/:id
/symphony/api/articles/82

And make POST requests to send data to Events for creating/updating.

The response formats can be either XML or JSON. When in “private” mode (the default) authors must authenticate, and in “public” mode you can choose which sections are available (a white-list).

It’s still in its infancy, but questions, comments and suggestions are muchly welcomed.

(Updated with new URLs)

This is great, thanks nick.

You could make little widgets (desktop publishing anyone?), or integrate symphony into other cms systems (not sure why though ;)).

This is a great idea! So do I understand correctly that you would POST directly to the same URLs that you are GETting? How about creating a new entry? B/c as I understand it, the REStful thing would be to POST to the section URL, and have the ID returned to you.

Another question would be what is the representation of the section by itself (called without an ID after it)? A basic index of existing child resources, or do you supply more info?

Just this week I have been reading up on AtomPub, and was considering how you could turn every section into an AtomPub resource. Since it supports arbitrary XML, you could include each field as an xml element (which could then support my dream of section fields having defined namespaces).

So do I understand correctly that you would POST directly to the same URLs that you are GETting? How about creating a new entry? B/c as I understand it, the REStful thing would be to POST to the section URL, and have the ID returned to you.

Correct, this is what happens.

To create a new entry under a section “Blog Posts”, send your POST here:

/symphony/api/blog-posts/

And the response will be the output of an event that creates an entry in that section. The ID is included in the response. (See Creating a new entry and Updating an existing entry in the README.)

The same is true for getting an existing entry and updating it:

Make a GET request and get the XML/JSON representation of an entry:

/symphony/api/blog-posts/42

Send a POST to the same URL to update the entry:

/symphony/api/blog-posts/42

Another question would be what is the representation of the section by itself (called without an ID after it)? A basic index of existing child resources, or do you supply more info?

A basic index of resources (entries). Just calling a section URL without additional parameters returns the Data Source with its defaults (limit to 20 entries, sorted by System ID descending).

(Updated with new URLs)

Greeeat work! #win

Why some APIs out there uses the Atom format? What’s the big deal?

Brilliant work, Nick. This paves the way for an Autosave extension and a generic Autocomplete extension, among other things…

@rainerborene

Here’s a very easy 9 minute overview. Watching this, I can’t help but think atom:collections = symphony:sections, atom:entry = symphony:entry.

Essentially, atom defines a common XML-based protocol for CRUDing a web resource collection.

Just this week I have been reading up on AtomPub, and was considering how you could turn every section into an AtomPub resource. Since it supports arbitrary XML, you could include each field as an xml element (which could then support my dream of section fields having defined namespaces).

It’s certainly a possibility. You’re more than welcome to fork the repo and add another content type to the output for Atom. Additional content types could include text, CSV and YAML.

Ultimately this extension began as a proof of concept to show the power of native Data Sources and Events in creating an API. I was reluctant to change the output in any way (except for changing the root node to always be response for consistency). Everything else is kept “Symphony-esque” to make things as easy to use: both querystring param naming and the XML output schema.

This is genius Nick!

The URL for autocomplete for a “Title” field in “Articles” would be as simple as:

/symphony/api/articles/?include=title&filter[title]=regexp:{keyword}&limit=10&output=json

This will filter the Articles section using a regexp filter on the Title field, returning a list of entries in JSON format that just includes the Title field for each entry, limited to 10 results.

An autosave of entry 42 in an “Articles” section would want to serialise an entry form (perhaps with jQuery’s serialize() function) and post it off to:

/symphony/api/articles/42/

(Updated with new URLs)

Question: what do people think about the API “stub” being /api/. Is this generic enough? Could it potentially clash with a Page on your site with the same URL? What are people’s preferences?

Personally, I’d prefer it to act as though it were part of the application - so /symphony/api is my vote. Very cool stuff, Nick - I’m excited about playing with this :)

/symphony/api is my vote

Great idea. KISS!

The extension now listens on /symphony/api/, and the .htaccess rule is added automatically when you install it for the first time.

This is a 0.1 release :-)

The API can now output a serialised PHP array (?output=serialise) for evaluating directly into PHP scripts, and also YAML (?output=yaml) using the spyc library.

Though I haven’t had a change to put it through it’s paces properly yet, this kick all sorts of ass, Nick.

Thanks Nick! This is probably the last thing that left me clinging to rails for a while now, simple REST integration.

the last thing that left me clinging to rails

Jump! Symphony knocks Ruby off its Rails ;-)

Nick, are you planning to integrate a DELETE method as well?

BTW: The readme on GitHub says:

• Updating an existing entry (POST)

Shoudn’t this be named PUT?