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.
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 /
- Accept: application/vnd.fcms.collection+json;version=1
- Accept-Charset: utf-8
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.
- 200: OK
{
"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.
- Accept: application/vnd.fcms.collection+json;version=1
- Accept-Charset: utf-8
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.
- 200: OK
- 404: the collection was not found
{
"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 /
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"
}
- Accept: application/vnd.fcms.collection+json;version=1
- Accept-Charset: utf-8
- Content-type: application/vnd.fcms.collection+json;version=1
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.
- 201: created
- 422: the collection entity you passed in is not valid
- Location: the URL of the newly created collection
{
"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
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.
- Accept: application/vnd.fcms.collection+json;version=1
- Accept-Charset: utf-8
- Content-type: application/vnd.fcms.collection+json;version=1
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.
- 200: update successful
- 404: the collection is not found
- 422: the item entity you passed in is not valid
{
"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"
}
]
}
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.
- num: how many items to return, optional, defaults to 50
- start: 0-based index of the 1st item to return, optional, defaults to 0
- Accept: application/vnd.collection+vnd.fcms.item+json;version=1
- Accept-Charset: utf-8
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.
- 200: OK
- 404: collection was not found
{
"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
- Accept: application/vnd.fcms.item+json;version=1
- Accept-Charset: utf-8
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.
- 200: OK
- 404: collection or item was not found
{
"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
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"
}
- Accept: application/vnd.fcms.item+json;version=1
- Accept-Charset: utf-8
- Content-type: application/vnd.fcms.item+json;version=1
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.
- 201: created
- 404: the collection is not found
- 422: the item entity you passed in is not valid
- Location: the URL of the newly created item
{
"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
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.
- Accept: application/vnd.fcms.item+json;version=1
- Accept-Charset: utf-8
- Content-type: application/vnd.fcms.item+json;version=1
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.
- 200: update successful
- 404: the collection, taxonomy or category is not found
- 422: the item entity you passed in is not valid
- Location: the URL of the newly created item
{
"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"
}
]
}
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:
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.
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"
}
]
}
Get a Taxonomy¶
Get a particular taxonomy.
Request¶
GET /:collection-slug/:taxonomy-slug
- Accept: application/vnd.fcms.taxonomy+json;version=1
- Accept-Charset: utf-8
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.
- 200: OK
- 404: collection or taxonomy was not found
{
"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"
}
]
}
- 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