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"
}
]
}