NAME

Strehler::API - App that gives a RESTful interface to Strehler data

DESCRIPTION

Strehler::API is an out-of-the-box API system designed to give back contents created with Strehler backend in a JSON (or JSONp) shape. It's main purpose is to make Strehler a complete server for client-side applications designed using advanced javascript, as Angular.js.

Articles and Images are exposed through API by default, all the other custom entities can be exposed as well. Exposed flag was created for that purpose.

All the API calls are under /api/v1/

API REFERENCE

Strehler::API are read-only API so there're just two calls you can do, both GET, to obtain data.

/api/v1/$entity/$entity_id

This API just return all the data related to entity $entity with id $entity_id. Data is always the extended data from get_ext_data in Strehler::Element. You can pass to the call lang as parameter to obtain data in a certain language. If no lang parameter is provided, data is returned using the default language. If the entity is publishable, only data from published articles is returned. Calling for an unpublished article return 404.

Example: /api/v1/article/15

/api/v1/$entity/slug/$slug

As the previous API, using article slug instead of ID. It works only with slugged entities, entities that has Strehler::Element::Role:Slugged as Strehler::Element::Article.

/api/v1/$plural_entity/$category/$subcategory/

This API returns in a JSON format a call to get_list sub from Strehler::Element. So data structure is:

    {
      page => 1,          #page retrieved
      last_page => 3,     #maximum callable page number
      to_view => $objects #list of objects, all returned with their extended data.
    } 

$plural_entity is the plural name of the entity. You can let Strehler derives it by itself from entity name using Lingua::EN::Inflect or you can configure it in the config.yml or in the class as all other attributes.

$category and $subcategory are optional. If you call the API using them you'll retrieve all the elements under $category/$subcategory category. Pay attention that if you just call /api/v1/$plural_entity/$category/ system will return the objects under $category and all the objects under $category's subcategories.

API output is controlled by many parameters (a subset of get_list available parameters):

    lang: output language, as for single item API
    order, order_by: to change the way elements are ordered
    page: to control pagination
    entries_per_page: to say how many elements display every page

Example: /api/v1/articles/foo/bar/

/api/v1/reference

Returns a web page where all the available APIs are listed. Automatically generated.

JSONP CALLBACK

Adding callback parameter to any API, return format will be JSONp instead of JSON.