Falkland CMS Hypermedia API

This is the documentation for using the Falkland CMS Hypermedia (REST) API.

Falkland CMS supports a Hypermedia (RESTful) API that can be used from any programming language to access all the capabilities of Falkland CMS.

The intent of this API is to be a true REST API in the full-fledged Roy Fielding, HATEOAS style. You can help with that by pointing out anything you perceive as a deviation.

Note

The example API calls in this documentation are provided in cURL. When exploring the API feel free to use cURL, the HTTP client of your choice, or the programming language you’re most comfortable in. It should be simple to convert the cURL example to your own preferred HTTP client.

Request Headers

Provide the custom Internet media type (formerly MIME type) saying you want Falkland CMS JSON data and the version of the API you are using in the header of your API requests.

Accept: application/vnd.fcms.{type} +json;version=version

Example: Accept: aapplication/vnd.fcms.item+json;version=1

The version of the API resource you want is determined by the Accept header that you pass in the request. If no version is provided, it is assumed you want the latest version.

API Security

Authentication

TBD.

Sessions

Access Control

TBD.

Resources

These resources are available in Falkland CMS:

Collections

A collection is a logical grouping of items to be managed together. A collection also has zero or more taxonomies that define hierarchical organizational structures for the items in the collection.

Some examples of collection:

  • Secondary sources about Albert Camus’ works for Camus.org
  • Everything there is on the Internet about mudskippers for Mudskippers.org
  • All the books in Jack Freeman’s Library
  • Everything published about amoralism for nil.org
  • All Atari 7800 games for 8-bit.com
  • Collected Buccaneer quotes for pitifulpirates.com
List Collections

List all the collections in the system.

Request
GET /
Headers
  • Accept: application/vnd.fcms.collection+json;version=1
  • Accept-Charset: utf-8
Example
curl -i --header "Accept: application/vnd.fcms.collection+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/
Response

The response has a JSON array called collections which contains each collection in the system. The response also contains a link for creating new collections.

Status
  • 200: OK
Example
{
   "collections":[
      {
         "name":"Mudskippers",
         "created_at":"2013-04-23T14:30:50Z",
         "updated_at":"2013-04-23T14:30:50Z",
         "links":[
            {
               "rel":"self",
               "method":"get",
               "href":"/mudskippers",
               "type":"application/vnd.fcms.collection+json;version=1"
            },
            {
               "rel":"contains",
               "method":"get",
               "href":"/mudskippers/",
               "type":"application/vnd.fcms.item+json;version=1"
            },
            {
               "rel":"create",
               "method":"post",
               "href":"/mudskippers/",
               "type":"application/vnd.fcms.item+json;version=1"
            },
            {
               "rel":"update",
               "method":"put",
               "href":"/mudskippers",
               "type":"application/vnd.fcms.collection+json;version=1"
            },
            {
               "rel":"delete",
               "method":"delete",
               "href":"/mudskippers",
            },
            {
               "rel":"taxonomy",
               "method":"get",
               "href":"/mudskippers/media-types",
               "type":"application/vnd.fcms.taxonomy+json;version=1"
            },
            {
               "rel":"taxonomy",
               "method":"get",
               "href":"/mudskippers/topics",
               "type":"application/vnd.fcms.taxonomy+json;version=1"
            }
         ]
      },
      {
         "name":"Secondary Sources on Albert Camus",
         "created_at":"2011-04-23T14:32:17Z",
         "updated_at":"2011-04-23T14:32:17Z",
         "links":[
            {
               "rel":"self",
               "method":"get",
               "href":"/camus",
               "type":"application/vnd.fcms.collection+json;version=1"
            },
            {
               "rel":"contains",
               "method":"get",
               "href":"/camus/",
               "type":"application/vnd.fcms.item+json;version=1"
            },
            {
               "rel":"create",
               "method":"post",
               "href":"/camus/",
               "type":"application/vnd.fcms.item+json;version=1"
            },
            {
               "rel":"update",
               "method":"put",
               "href":"/camus",
               "type":"application/vnd.fcms.collection+json;version=1"
            },
            {
               "rel":"delete",
               "method":"delete",
               "href":"/camus",
            },
            {
               "rel":"taxonomy",
               "method":"get",
               "href":"/camus/media-types",
               "type":"application/vnd.fcms.taxonomy+json;version=1"
            },
            {
               "rel":"taxonomy",
               "method":"get",
               "href":"/camus/issues",
               "type":"application/vnd.fcms.taxonomy+json;version=1"
            },
            {
               "rel":"taxonomy",
               "method":"get",
               "href":"/camus/geography",
               "type":"application/vnd.fcms.taxonomy+json;version=1"
            }
         ]
      }
   ],
   "links":[
      {
         "rel":"create",
         "method":"post",
         "href":"/",
         "type":"application/vnd.fcms.collection+json;version=1"
      }
   ]
}
Get a Collection

Get a particular collection.

Request
GET         /:collection-slug

Warning

The lack of a trailing slash after the slug is important.

Headers
  • Accept: application/vnd.fcms.collection+json;version=1
  • Accept-Charset: utf-8
Example
curl -i --header "Accept: application/vnd.fcms.collection+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/mudskippers
Response

The response has a complete JSON representation of the collection which contains links to available actions on the collection, and links to any taxonomies associated with the collection.

Status
  • 200: OK
  • 404: the collection was not found
Example
{
   "name":"Mudskippers",
   "created_at":"2013-04-23T14:30:50Z",
   "updated_at":"2013-04-23T14:30:50Z",
   "slug":"mudskippers",
   "description":"The Internet's best resources on the Mudskipper",
   "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"contains",
         "method":"get",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"create",
         "method":"post",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/mudskippers",
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskippers/media-types",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskippers/topics",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      }
   ]
}
Create a Collection

Create a new collection in the system.

Request
POST /
Parameters

Pass in details for the new collection as a JSON representation. The name is required and will be used to create the slug if no slug is provided.

Here is a minimal representation of a JSON body:

{
   "name":"Mudskippers"
}

Here is a more complete representation of a JSON body:

{
   "name":"Mudskippers",
   "taxonomy":"/mudskippers/media-types",
   "taxonomy":"/mudskippers/topics",
   "description":"The Internet's best resources on the Mudskipper"
}
Headers
  • Accept: application/vnd.fcms.collection+json;version=1
  • Accept-Charset: utf-8
  • Content-type: application/vnd.fcms.collection+json;version=1
Example
curl -i --header "Accept: application/vnd.fcms.collection+json;version=1" --header "Accept-Charset: utf-8" --header "Content-type: application/vnd.fcms.collection+json;version=1" -X POST -d '{"name":"Mudskippers","taxonomy":"/mudskippers/media-types","taxonomy":"/mudskippers/topics","description":"The Internet's best resources on the Mudskipper"}' http://{host:port}/
Response

The new collection is at the location provided in the location in the header. A representation of the new collection is also returned.

Status
  • 201: created
  • 422: the collection entity you passed in is not valid
Headers
  • Location: the URL of the newly created collection
Example
{
   "name":"Mudskippers",
   "created_at":"2013-04-23T14:30:50Z",
   "updated_at":"2013-04-23T14:30:50Z",
   "slug":"mudskippers",
   "description":"The Internet's best resources on the Mudskipper",
   "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"contains",
         "method":"get",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"create",
         "method":"post",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/mudskippers",
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskippers/media-types",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskippers/topics",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      }
   ]
}
Update a Collection

Update an existing collection.

Request
PUT /:collection-slug
Parameters

Pass in details for the updated collection as a JSON representation. The name is required.

If no slug is provided in the JSON representation, the existing slug will be used.

{
   "name":"Mudskipper",
   "slug":"mudskipper-info",
   "taxonomy":"/mudskippers/topics",
   "description":"The world's best resources on the Mudskipper"
}

Note

Provide a new slug in the JSON body to move a collection.

Headers
  • Accept: application/vnd.fcms.collection+json;version=1
  • Accept-Charset: utf-8
  • Content-type: application/vnd.fcms.collection+json;version=1
Example
curl -i --header "Accept: application/vnd.fcms.collection+json;version=1" --header "Accept-Charset: utf-8" --header "Content-type: application/vnd.fcms.item+json;version=1" -X PUT -d '{"name":"Mudskipper","slug":"mudskipper-info","taxonomy":"/mudskippers/topics","description":"The world's best resources on the Mudskipper"}' http://{host:port}/mudskippers
Response

The representation of the updated collection is at the specified location, which is echoed in the location in the header. A representation of the updated collection is also returned.

Status
  • 200: update successful
  • 404: the collection is not found
  • 422: the item entity you passed in is not valid
Example
{
   "name":"Mudskippers",
   "created_at":"2013-04-23T14:30:50Z",
   "updated_at":"2013-04-23T14:30:50Z",
   "slug":"mudskipper-info",
   "description":"The world's best resources on the Mudskipper",
   "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/mudskipper-info",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"contains",
         "method":"get",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"create",
         "method":"post",
         "href":"/mudskippers/",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/mudskipper-info",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/mudskipper-info",
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskipper-info/media-types",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"taxonomy",
         "method":"get",
         "href":"/mudskipper-info/topics",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      }
   ]
}
Delete a Collection

Delete an existing collection.

Request
DELETE /:collection-slug
Example
curl -i -X DELETE http://{host:port}/mudskippers
Response

There is no response body, just a status.

Status
  • 204: deleted
  • 404: collection was not found

Items

An item is a single reference entry in a collection. An item is referential. It’s not itself the member of the collection, but is a pointer to the member of the collection. It’s not the article on Faulkner’s early history with bedwetting, it’s a pointer to the article.

With Falkland CMS, you capture items in a collection and categorize them into multiple orthogonal taxonomies. Items can point to literally anything in the world: books, articles, web pages, videos, art, artifacts, quotes, collectables, et cetera. An item is simply anything in a collection that is big enough to warrant spending the time to organize the collection. Once created, items can be browsed and searched, and can be displayed in exhibits.

Some examples of items:

  • an item for the Dracula VIC-20 cartridge for vic20.com
  • an item for a journal article about The Fall for Camus.org
  • an item for a book, The Fall, in Jack Freeman’s Library
  • an item for a Youtube video about mudskippers for Mudskippers.org
  • an item for the wikipedia entry on amoralism for nil.org
  • an item for the definition of the acronym PC for Falklandsophile.com
  • an item for a John McKay quote for pitifulpirates.com
List Items

List all the items in a collection.

Request
GET /:collection-slug/?num=50&start=200

Warning

The trailing slash after the collection slug is important and must be included in the request.

Parameters
  • num: how many items to return, optional, defaults to 50
  • start: 0-based index of the 1st item to return, optional, defaults to 0
Headers
  • Accept: application/vnd.collection+vnd.fcms.item+json;version=1
  • Accept-Charset: utf-8
Example
curl -i --header "Accept: application/vnd.collection+vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/mudskippers/

curl -i --header "Accept: application/vnd.collection+vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/mudskippers/?num=100

curl -i --header "Accept: application/vnd.collection+vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/mudskippers/?num=10&start=10
Response

The response is a Collection+JSON collection hash (not to be confused with an FCMS collection) which contains an array called items with each item in the collection. The collection hash contains an array of links for creating new items in the collection and for pagination. The collection hash also contains a template in JSON Schema format for creating new items in the collection.

Status
  • 200: OK
  • 404: collection was not found
Example
{
   "collection": {
      "version": "1.0",
      "href": "/mudskippers?num=2&start=4",
      "links":[
         {
            "rel":"create",
            "method":"post",
            "href":"/mudskippers",
            "type":"application/vnd.fcms.item+json;version=1"
         },
         {
            "rel":"first",
            "method":"get",
            "href":"/mudskippers?num=2",
            "type":"application/vnd.fcms.item+json;version=1"
         },
         {
            "rel":"prev",
            "method":"get",
            "href":"/mudskippers?num=2&start=2",
            "type":"application/vnd.fcms.item+json;version=1"
         },
         {
            "rel":"next",
            "method":"get",
            "href":"/mudskippers?num=2&start=6",
            "type":"application/vnd.fcms.item+json;version=1"
         }
      ],
      "items":[
         {
            "name":"Amazing animals - Mudskipper",
            "URL":"http://www.youtube.com/watch?v=mJhUKzEq47U",
            "created_at":"2013-04-23T14:30:50Z",
            "updated_at":"2013-04-23T14:30:50Z",
            "slug":"amazing-animals-mudskipper",
            "collection":"mudskippers",
            "description":"Excerpt from David Attenborough's BBC Life series episode 04",
            "links":[
               {
                  "rel":"self",
                  "method":"get",
                  "href":"/mudskippers/amazing-animals-mudskipper",
                  "type":"application/vnd.fcms.item+json;version=1"
               },
               {
                  "rel":"update",
                  "method":"put",
                  "href":"/mudskippers/amazing-animals-mudskipper",
                  "type":"application/vnd.fcms.item+json;version=1"
               },
               {
                  "rel":"delete",
                  "method":"delete",
                  "href":"/mudskippers/amazing-animals-mudskipper"
               },
               {
                  "rel":"category",
                  "method":"get",
                  "href":"/mudskippers/media-types/videos/online",
                  "type":"application/vnd.fcms.category+json;version=1"
               },
               {
                  "rel":"category",
                  "method":"get",
                  "href":"/mudskippers/topics/reproduction",
                  "type":"application/vnd.fcms.category+json;version=1"
               },
               {
                  "rev":"collection",
                  "method":"get",
                  "href":"/mudskippers",
                  "type":"application/vnd.fcms.collection+json;version=1"
               }
            ]
         },
         {
            "name":"Mudskipper's Habitat",
            "URL": "http://animal.discovery.com/tv-shows/animal-planet-presents/videos/whats-to-love-mudskippers-habitat.htm",
            "created_at":"2011-04-23T14:32:17Z",
            "updated_at":"2011-04-23T14:32:17Z",
            "slug":"mudskippers-habitat",
            "collection":"mudskippers",
            "description":"Animal Planet Presents Mudskipper's Habitat",
            "links":[
               {
                  "rel":"self",
                  "method":"get",
                  "href":"/mudskippers/mudskippers-habitat",
                  "type":"application/vnd.fcms.item+json;version=1"
               },
               {
                  "rel":"update",
                  "method":"put",
                  "href":"/mudskippers/mudskippers-habitat",
                  "type":"application/vnd.fcms.item+json;version=1"
               },
               {
                  "rel":"delete",
                  "method":"delete",
                  "href":"/mudskippers/mudskippers-habitat"
               },
               {
                  "rel":"category",
                  "method":"get",
                  "href":"/mudskippers/media-types/videos/online",
                  "type":"application/vnd.fcms.category+json;version=1"
               },
               {
                  "rel":"category",
                  "method":"get",
                  "href":"/mudskippers/topics/habitat",
                  "type":"application/vnd.fcms.category+json;version=1"
               },
               {
                  "rev":"collection",
                  "method":"get",
                  "href":"/mudskippers",
                  "type":"application/vnd.fcms.collection+json;version=1"
               }
            ]
         }
      ],
      "template":{
         "$schema": "http://json-schema.org/draft-04/schema#",
         "title": "Item",
         "description": "A new item in the Mudskippers collection.",
         "type": "object",
         "properties": {
            "name": {
               "prompt": "Name",
               "description": "A natural language identifier for the item, does not need to be unique.",
               "type": "string"
            },
            "url": {
               "prompt": "Link",
               "description": "A URL pointer to the resource referred to by the item.",
               "type": "string"
            },
            "slug": {
               "prompt": "Slug",
               "description": "An identifier for the item, must be unique in the collection, will be derived from name if not provided.",
               "type": "string",
               "maxLength": 256
            },
            "description": {
               "prompt": "Description",
               "description": "A natural language description of the item.",
               "type": "string"
            },
            "categories": {
               "prompt": "Categories",
               "description": "The leaf categories this item is a member of.",
               "type": "array",
               "items": {
                  "prompt": "Path",
                  "description": "The forward slash delimited path to the category",
                  "type": "string"
               },
               "minItems": 0,
               "uniqueItems": true
            }
         },
         "required": ["name"]
      }
   }
}
Get an Item

Get a particular item.

Request
GET /:collection-slug/:item-slug
Headers
  • Accept: application/vnd.fcms.item+json;version=1
  • Accept-Charset: utf-8
Example
curl -i --header "Accept: application/vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/mudskippers/amazing-animals-mudskipper
Response

The response has a complete JSON representation of the item which contains links to available actions on the item, a reverse link to the collection containing the item, and links to any categories the item is a member of.

Status
  • 200: OK
  • 404: collection or item was not found
Example
{
  "slug": "amazing-animals-mudskipper",
  "collection": "mudskippers",
  "created_at": "2013-04-23T14:30:50Z",
  "updated_at": "2013-04-23T14:30:50Z",
  "version": "1",
  "properties": {
    "@context": {
      "dc": "http://purl.org/dc/elements/1.1/"
    },
    "dc:creator": "David Attenborough",
    "dc:date": "2009",
    "dc:description": "Excerpt from David Attenborough's BBC Life series episode 04",
    "dc:identifier": [
      "http://www.youtube.com/watch?v=mJhUKzEq47U",
      "http://www.metacafe.com/watch/yt-KurTiX4FDuQ/amazing_animals_mudskipper/"
    ],
    "dc:language": "en",
    "dc:publisher": [
      "BBC",
      "British Broadcasting Corporation"
    ],
    "dc:subject": [
      {
        "@id": "/mudskippers/topics/reproduction",
        "name": "Reproduction"
      }
    ],
    "dc:title": [
      "Amazing animals - Mudskipper - Episode 4",
      "Mudskipper"
    ],
    "dc:type": [
      {
        "@id": "/mudskippers/media-types/videos/online",
        "name": "Online Video"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "method": "get",
      "href": "/mudskippers/amazing-animals-mudskipper",
      "type": "application/vnd.fcms.item+json;version=1"
    },
    {
      "rel": "update",
      "method": "put",
      "href": "/mudskippers/amazing-animals-mudskipper",
      "type": "application/vnd.fcms.item+json;version=1"
    },
    {
      "rel": "delete",
      "method": "delete",
      "href": "/mudskippers/amazing-animals-mudskipper"
    },
    {
      "rel": "category",
      "method": "get",
      "href": "/mudskippers/media-types/videos/online",
      "type": "application/vnd.fcms.category+json;version=1"
    },
    {
      "rel": "category",
      "method": "get",
      "href": "/mudskippers/topics/reproduction",
      "type": "application/vnd.fcms.category+json;version=1"
    },
    {
      "rev": "collection",
      "method": "get",
      "href": "/mudskippers",
      "type": "application/vnd.fcms.collection+json;version=1"
    }
  ]
}
Create an Item

Create a new item in a collection.

Request
POST /:collection-slug
Parameters

Pass in details for the new item as a JSON representation. The name is required and will be used to create the slug.

Here is a minimal representation of a JSON body:

{
   "name":"Mudskipper",
   "URL":"http://en.wikipedia.org/wiki/Mudskipper"
}

Here is a more complete representation of a JSON body:

{
   "name":"Mudskipper",
   "URL":"http://en.wikipedia.org/wiki/Mudskipper",
   "categories": [
      "/mudskippers/media-types/articles/online",
      "/mudskippers/topics/general"
   ],
   "description":"Mudskipper entry from Wikipedia, the free encyclopedia"
}
Headers
  • Accept: application/vnd.fcms.item+json;version=1
  • Accept-Charset: utf-8
  • Content-type: application/vnd.fcms.item+json;version=1
Example
curl -i --header "Accept: application/vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" --header "Content-type: application/vnd.fcms.item+json;version=1" -X POST -d '{"name":"Mudskipper","URL":"http://en.wikipedia.org/wiki/Mudskipper","category":"/mudskippers/media-types/articles/online","category":"/mudskippers/topics/general","description":"Mudskipper entry from Wikipedia, the free encyclopedia"}' http://{host:port}/mudskippers/
Response

The new item is at the location provided in the location in the header. A representation of the new item is also returned.

Status
  • 201: created
  • 404: the collection is not found
  • 422: the item entity you passed in is not valid
Headers
  • Location: the URL of the newly created item
Example
{
   "name":"Mudskipper",
   "URL":"http://en.wikipedia.org/wiki/Mudskipper",
   "created_at":"2013-04-23T14:30:50Z",
   "updated_at":"2013-04-23T14:30:50Z",
   "slug":"wiki-mudskipper",
   "collection":"mudskippers",
   "description":"Mudskipper entry from Wikipedia, the free encyclopedia",
   "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/mudskippers/wikipedia-mudskipper",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/mudskippers/wikipedia-mudskipper",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/mudskippers/wikipedia-mudskipper",
      },
      {
         "rel":"category",
         "method":"get",
         "href":"/mudskippers/media-types/articles/online",
         "type":"application/vnd.fcms.category+json;version=1"
      },
      {
         "rel":"category",
         "method":"get",
         "href":"/mudskippers/topics/general",
         "type":"application/vnd.fcms.category+json;version=1"
      },
      {
         "rev":"collection",
         "method":"get",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      }
   ]
}
Update an Item

Update an existing item.

Request
PUT /:collection-slug/:item-slug
Parameters

Pass in details for the updated item as a JSON representation. The name is required.

If no slug is provided in the JSON representation, the existing slug will be used.

{
   "name":"Mudskipper",
   "slug":"wiki-mud",
   "URL":"http://en.wikipedia.org/wiki/Mudskipper",
   "categories": [
      "/mudskippers/topics/general"
   ]
   "description":"Mudskipper entry from Wikipedia, the free encyclopedia"
}

Note

Provide a new slug in the JSON body to move an item.

Headers
  • Accept: application/vnd.fcms.item+json;version=1
  • Accept-Charset: utf-8
  • Content-type: application/vnd.fcms.item+json;version=1
Example
curl -i --header "Accept: application/vnd.fcms.item+json;version=1" --header "Accept-Charset: utf-8" --header "Content-type: application/vnd.fcms.item+json;version=1" -X PUT -d '{"name":"Mudskipper","slug":"wiki-mud","URL":"http://en.wikipedia.org/wiki/Mudskipper","category":"/mudskippers/topics/general","description":"Mudskipper entry from Wikipedia, the free encyclopedia"}' http://{host:port}/mudskippers/media-types/articles/online/wikipedia-mudskipper
Response

The representation of the updated item is at the specified location, which is echoed in the location in the header. A representation of the updated item is also returned.

Status
  • 200: update successful
  • 404: the collection, taxonomy or category is not found
  • 422: the item entity you passed in is not valid
Headers
  • Location: the URL of the newly created item
Examples
{
   "name":"Amazing animals - Mudskipper",
   "URL":"http://www.youtube.com/watch?v=mJhUKzEq47U",
   "created_at":"2013-04-23T14:30:50Z",
   "updated_at":"2013-04-23T14:30:50Z",
   "slug":"amazing-animals-mudskipper",
   "collection":"mudskippers",
   "description":"Excerpt from David Attenborough's BBC Life series episode 04",
   "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/mudskippers/amazing-animals-mudskipper"
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/mudskippers/amazing-animals-mudskipper",
         "type":"application/vnd.fcms.item+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/mudskippers/amazing-animals-mudskipper",
      },
      {
         "rel":"category",
         "method":"get",
         "href":"/mudskippers/media-types/videos/online",
         "type":"application/vnd.fcms.category+json;version=1"
      },
      {
         "rel":"category",
         "method":"get",
         "href":"/mudskippers/topics/reproduction",
         "type":"application/vnd.fcms.category+json;version=1"
      },
      {
         "rev":"collection",
         "method":"get",
         "href":"/mudskippers",
         "type":"application/vnd.fcms.collection+json;version=1"
      }
   ]
}
Delete an Item

Delete an existing item.

Request
DELETE /:collection-slug/:item-slug
Example
curl -i -X DELETE http://{host:port}/mudskippers/amazing-animals-mudskipper
Response

There is no response body, just a status.

Status
  • 204: deleted
  • 404: collection or item was not found

Taxonomies

A taxonomy is a hierarchical classification of items in a collection. A taxonomy is made up of a tree of categories from the more general at the root of the taxonomy to the more specific at the leaves of the taxonomy. Here is a simple abbreviated example of a taxonomy of US locations:

Sample US Location Taxonomy

In the example the taxonomy is called “Location” and it consists of categories such as “Continental US” and “Florida”.

An item classified in a category in a taxonomy is a member of that category and all of that category’s parents. As an illustrative example, imagine an item, “Mecklenburg Declaration of Independence”, classified with the category “North Carolina”. It’s also a member of “South East”, “Continental US” and the “Location” taxonomy as a whole.

Sample Item in US Location Taxonomy

With Falkland CMS, it is typical to have multiple orthogonal taxonomies categorizing the items in a collection.

In addition to being classified in multiple different taxonomies, items can also be categorized in more than 1 category in the same taxonomy. In fact, as has been pointed out above, it is rare for items to be categorized in just one category in a taxonomy since they are members of their categories’ parent categories as well.

Categories have a slug and a path. The category slug must follow all the standard rules for slugs in Falkland-CMS and must be unique to all other categories at the same level and location in the same taxonomy. The path to a category is made up of the collection, the taxonomy slug, all the parent slugs and finally the category slug. In our sample taxonomy for example, the slug for the “North Carolina” category is “north-carolina” and the path is:

/founding-documents/location/continental-us/south-east/north-carolina/

Listing items at the path above means the “Mecklenburg Declaration of Independence” will be listed since it is classified in the “North Carolina” category, and listing the items in the following paths would also include the “Mecklenburg Declaration of Independence”:

  • /founding-documents/location/continental-us/south-east/
  • /founding-documents/location/continental-us/
  • /founding-documents/location/
  • /founding-documents/

Some examples of taxonomies:

  • type of media
  • type of document
  • geographic location
  • topic
  • time period
  • biological classification
  • chemical classification
  • Dewey Decimal Classification
  • folk taxonomies

There is an extensive list of taxonomies at the Taxonomy Warehouse.

The categories in a taxonomy are represented as name/value pairs with the name being the category slug and the value being the category name. The structure of the taxonomy is represented as name/value pairs with the name being the word “categories” and the value being an array of categories.

Here is a fragmentary example of the JSON representation of the sample taxonomy depicted above:

{
  "name":"Location",
  "slug":"location",
  "collection":"founding-documents",
  "description":"US Location",
  "categories": [
        {"continental-us": "Continental US", "categories": [
                {"north-east": "North East"},
                {"south-east": "South East", "categories": [
                        {"florida": "Florida"},
                        {"georgia": "Georgia"},
                        {"north-carolina": "North Carolina"},
                        {"south-carolina": "South Carolina"},
                        {"tennessee": "Tennessee"},
                        {"alabama": "Alabama"}
                ]},
                {"midwest": "Midwest"},
                {"south": "South"},
                {"southwest": "Southwest"},
                {"west": "West"}]},
        {"non-continental-us": "Outiside Continental US"}
  ]
}

Here is complete example of the entire JSON representation of a taxonomy:

{
  "name":"Topics",
  "created_at":"2013-06-23T05:30:50Z",
  "updated_at":"2013-06-23T05:30:50Z",
  "slug":"topics",
  "collection":"falkland-islands",
  "description":"",
  "categories": [
                {"natural-history" : "Natural History", "categories": [
                {"flora": "Flora"},
                        {"insects": "Insects"},
                        {"fishes": "Fishes"},
                        {"birds": "Birds", "categories": [
                                {"penguins": "Penguins"}
                        ]},
                        {"mammals": "Mammals"}]},
                {"pre-20th-century-history": "Pre-20th Century History", "categories": [
                {"naval": "Naval"},
                        {"legal-political": "Legal / Political"},
                        {"darwin": "Charles Darwin"}
                ]},
                {"modern-history": "Modern History", "categories": [
                        {"naval": "Naval"},
                        {"legal-political": "Legal / Political"}
                ]},
                {"military-history": "Military History", "categories": [
                        {"ww1": "World War I"},
                        {"ww2": "WW II History"},
                        {"1982": "1982 Falklands War", "categories": [
                                {"political": "Political", "categories": [
                                        {"thatcher": "Margaret Thatcher"}
                                ]},
                                {"naval": "Naval", "categories": [
                                        {"uk": "UK", "categories": [
                                                {"sheffield": "HMS Sheffield"},
                                                {"invincible": "HMS Invincible"},
                                                {"hermes": "HMS Hermes"},
                                                {"conqueror": "HMS Conqueror"},
                                                {"canberra": "SS Canberra"},
                                                {"qe2": "HMS Queen Elizabeth 2"},
                                                {"galahad-tristram": "RFA Sir Galahad & RFA Sir Tristram"}
                                        ]},
                                        {"argentina": "Argentina", "categories": [
                                                {"belgrano": "ARA General Belgrano"}
                                        ]}
                                ]},
                                {"air": "Air", "categories": [
                                        {"uk": "UK", "categories": [
                                                {"harrier": "Harrier"},
                                                {"Vulcan": "Vulcan"}
                                        ]},
                                        {"argentina": "Argentina"}]},
                                {"ground": "Ground", "categories": [
                                        {"uk": "UK", "categories": [
                                                {"3-commando": "3 Commando Brigade", "categories": [
                                                {"sas": "SAS"},
                                                        {"40-commando": "40 Commando, Royal Marines"},
                                                        {"42-commando": "42 Commando, Royal Marines"},
                                                        {"45-commando": "45 Commando, Royal Marines"},
                                                        {"2-para": "2nd Battalion, Parachute Regiment"},
                                                        {"3-para": "3rd Battalion, Parachute Regiment"}
                                                ]},
                                                {"5-infantry": "5th Infantry Brigade",  "categories": [
                                                        {"welsh-guards": "Welsh Guards"},
                                                        {"scots-guards": "Scots Guards"},
                                                        {"gurkhas": "Gurkta Rifles"}
                                                ]}
                                        ]},
                                        {"argentina": "Argentian"}
                                ]},
                                {"Civilian": "civilian"}
                        ]}
                ]},
        {"society": "Society", "categories": [
                {"people": "People"},
                {"sports": "Sports"},
                {"food": "Food"},
                {"industry": "Industry", "categories": [
                        {"agriculture": "Agriculture"},
                          {"fisheries": "Fisheries"},
                          {"hydrocarbons": "Oil & Gas"}
                        ]},
                {"government": "Government", "categories": [
                        {"constitution": "Constitution"},
                        {"legislative-assembly": "Legislative Assembly", "categories": [
                                {"executive-council": "Executive Council"}
                        ]},
                        {"judiciary": "Judiciary"},
                        {"police": "Police"},
                        {"governor": "Governor"}
                ]},
                {"tourism": "Tourism", "categories": [
                        {"lodging": "Lodging"},
                        {"tours": "Tours"},
                                {"guides": "Guides"}
                        ]}
                ]},
        {"fiction": "Fiction"}
  ],
  "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/falkland-islands/topics",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/falkland-islands/topics",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/falkland-islands/topics"
      },
      {
         "rev":"collection",
         "method":"get",
         "href":"/falkland-islands",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Topics"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/natural-history/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Natural History"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/modern-history/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Modern History"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/military-history/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Militiary History"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/society/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Society"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/falkland-islands/topics/fiction/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Fiction"
      }
   ]
}
List Taxonomies

List all the taxonomies in a collection.

TODO

Get a Taxonomy

Get a particular taxonomy.

Request
GET /:collection-slug/:taxonomy-slug
Headers
  • Accept: application/vnd.fcms.taxonomy+json;version=1
  • Accept-Charset: utf-8
Example
curl -i --header "Accept: application/vnd.fcms.taxonomy+json;version=1" --header "Accept-Charset: utf-8" -X GET http://{host:port}/founding-documents/location
Response

The response has a complete JSON representation of the taxonomy which contains the hierarchical structure of the categories in the taxonomy, links to available actions on the taxonomy, a reverse link to the collection containing the taxonomy, and links to listings items categorized in the taxonomy.

Status
  • 200: OK
  • 404: collection or taxonomy was not found
Example
{
  "name":"Location",
  "created_at":"2013-08-14T05:43:07Z",
  "updated_at":"2013-08-14T05:43:07Z",
  "slug":"location",
  "collection":"founding-documents",
  "description":"US Location",
  "categories": [
        {"continental-us": "Continental US", "categories": [
                {"north-east": "North East"},
                {"south-east": "South East", "categories": [
                        {"florida": "Florida"},
                        {"georgia": "Georgia"},
                        {"north-carolina": "North Carolina"},
                        {"south-carolina": "South Carolina"},
                        {"tennessee": "Tennessee"},
                        {"alabama": "Alabama"}
                ]},
                {"midwest": "Midwest"},
                {"south": "South"},
                {"southwest": "Southwest"},
                {"west": "West"}]},
        {"non-continental-us": "Outiside Continental US"}
  ],
  "links":[
      {
         "rel":"self",
         "method":"get",
         "href":"/founding-documents/location",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"update",
         "method":"put",
         "href":"/founding-documents/location",
         "type":"application/vnd.fcms.taxonomy+json;version=1"
      },
      {
         "rel":"delete",
         "method":"delete",
         "href":"/founding-documents/location"
      },
      {
         "rev":"collection",
         "method":"get",
         "href":"/founding-documents",
         "type":"application/vnd.fcms.collection+json;version=1"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/founding-documents/location/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Topics"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/founding-documents/location/continental-us/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Continental US"
      },
      {
         "rev":"browse",
         "method":"get",
         "href":"/founding-documents/location/non-continental-us/",
         "type":"application/vnd.fcms.item+json;version=1",
         "name": "Outside Continental US"
      }
   ]
}
Create a Taxonomy

Create a new taxonomy in a collection.

TODO

Update a Taxonomy

Update an existing taxonomy.

TODO

Delete a Taxonomy

Delete an existing taxonomy.

Request
DELETE /:collection-slug/:taxonomy-slug
Example
curl -i -X DELETE http://{host:port}/founding-documents/location
Response

There is no response body, just a status.

Status
  • 204: deleted
  • 404: collection or taxonomy was not found
  • Collection: a group of curated items, a Falkland CMS system can have one or more collections
  • Item: a single entry in a collection. An item is not itself THE member of the collection, but is a pointer TO the member of the collection.
  • Taxonomy: - a hierarchical categorization of items in a collection, collections typically have multiple independent taxonomies

Slugs

Each of these resources has a slug that’s used when referring to the resource in a URL. A slug is just a unique identifier that’s suitable for use in a URL. Slugs in Falkland CMS are:

  • alphanumeric (no white space, unicode or special characters)
  • lower case
  • internally separated by a single dash
  • without a prefixed or trailing dash
  • 256 characters or less

An example of a slug is: the-amazing-amphibious-fish

You don’t need to be overly concerned about these rules as Falkland CMS always gives you the option of having the slug generated from the resource’s name.

All items must have unique slugs that do not conflict with other items in the same collection since they operate in the same namespace: /:collection-slug/:item-slug

Similarly all taxonomies must have unique slugs that do not conflict with other taxonomies in the same collection since they operate in the same namespace: /:collection-slug/:taxonomy-slug

As you would expect, all collections must have unique slugs as well that do not conflict with other collections.

Category slugs are more flexible and only need to be unique with other categories at their same level in the same taxonomy. So the following examples where different categories share the same slug (“online” and “physical-media”) in the same taxonomy are perfectly fine:

  • /mudskippers/type/video/physical-media
  • /mudskippers/type/video/online
  • /mudskippers/type/book/physical-media
  • /mudskippers/type/book/online