API Overview
REST (REpresentational State Transfer) is a technique for providing web services that leverages the built-in capabilities of HTTP, the protocol that drives the web. In REST, like in the web itself, data objects are represented as resources, and HTTP provides verbs that act upon them.
The initial discussion of REST as an architectural style occurs in Roy Thomas Fielding's dissertation.
API Resources
A URL is a Uniform Resource Locator, which is a method for specifying web resources, and a URL is used to represent all Siteframe resources as well. Specifically, all data items on a Siteframe website are represented by resources in this format:
<site URL> + api + <version> + <resource> + (optional) <identifier>
- The <site URL> is your website's URL, specified as site_url in the siteframe.ini file.
- api is a literal string used to differentiate the API from other website functions.
- The version is currently V1; this may be modified in the future, and is provided to ensure backwards-compatibility in case of future modifications to the API.
- The resource part corresponds exactly to a Siteframe data class name; for example, "Page," "Folder," "User," or "Tag."
- Finally, the optional identifier is the numeric ID or tag name of the object; for example, a user can be identified by a user ID ("2") or unique name ("glen").
Put them all together, and you get something that looks like this:
http://siteframe.org/api/V1/User/glen*
This is an API resource that represents a "User" object with the name "glen" on the site "http://siteframe.org." Click here for a complete list of API resources.
*Note that there is an alternative syntax in case you are running on a server (or through a web-host provider) that doesn't permit URL rewriting:
http://siteframe.org/api.php?v=1&r=resource ( &id=identifier )
Other than manually specifying the v= and r= version and resource components, everything else stays the same.
HTTP Verbs
HTTP verbs are used to fetch or alter the API resources. Specifically, the verbs GET, POST, and DELETE are supported:
- GET is used to retrieve a resource.
- POST is used to create or update a resource.
- DELETE is used to, well, delete a resource.
The most common verb is GET; this simply retrieves an XML representation of the resource. In some cases, GET is the only verb supported; these are called "read-only" resources (for obvious reasons). POST, when used with a resource that has no identifier, will create a new resource; if the identifier is provided, then POST will attempt to update it. DELETE will attempt to delete a resource, and thus the identifier is required.
Authentication
To prevent Very Bad People from messing around with your site's data, users to use the API must have an API key; this is a specially-encoded string that is unique for each user (you can see your API key on your user's page). When the key is provided, in essence, the user requesting the API operation "becomes" the user whose key is used; thus, it is very important to keep your key secure and not to share it with anyone else.
The API key is provided with the key parameter via either POST data or the query string:
http://siteframe.org/api/V1/User/glen?key=very-long-string-of-stuff
By default, any API operation requires an API key. However, the site administrator can set api_key_required=Off in siteframe.ini to allow GET requests without a key. POST and DELETE requests always require a key, since user authentication is required to create, update, or delete objects.
The same security restrictions are in place on the API user represented by the key as on the original user on the website. That is, if I am signed on to http://siteframe.org as user "glen," I can only edit or delete objects that I own. Likewise, someone with my API key can only update or delete objects as user "glen."
