META vocab resource
Contents |
Overview
The META API's 'vocab' resource allows you to create and manage vocabularies.
A vocabulary essentially consists of a name and an XML namespace (= URL) which are used to qualify the metadata names, depending on the resource and the protocol that is being used for formatting (e.g. ATOM, RSS, JSON). For example: when retrieving XML formatted data, the vocabulary name is being used as an XML namespace shortener.
Actions
- GET http://meta.meta03.rambla.be/vocab/{username}/[{vocab}/]
- POST http://meta.meta03.rambla.be/vocab/{username}/[{vocab}/]
- DELETE http://meta.meta03.rambla.be/vocab/{username}/{vocab}/
Content
A "vocab" instance contains 3 parameters describing the resource:
- name : vocabulary name (= required). If applicable, the name should correspond to the XML namespace prefix for this vocabulary (e.g. "dc" -> Dublin Core). This name may only consist of alphanumerical US-ASCII characters, dots, hyphens and underscores (48 maximum).
- xml_namespace : URL of the (XML) namespace (e.g. http://purl.org/dc/elements/1.1/) (= required).
- description : human readable description (= optional)
Tip: if you define your own xml_namespace URLs, make sure that they end with a forward slash. Even though this is not required for XML standards, it will improve interoperability with other formats.
Some well-known vocabularies like 'dc' (Dublin Core) and 'media' (Media RSS) do not have to be created. When you use them to qualify a meta object, the META service will automatically create the vocab instance and set the correct xml namespace. If you do create them, the META service will set the correct xml_namespace even if it differs from the xml_namespace that you specified.
GET
GET http://meta.meta03.rambla.be/vocab/{username}/[{vocab}/]
Retrieves a list of vocabularies or a single vocab instance.
For example:
- http://meta.meta01.rambla.be/vocab/monty/ : returns a list of vocab objects belonging to user 'monty'
- http://meta.meta01.rambla.be/vocab/monty/dc/ : returns a vocab object that represents user monty's Dublin Core vocabulary
Example of a vocab list:
{
"feed": {
"entry": [{
"content": {
"params": {
"name": "rss",
"xml_namespace": "http://backend.userland.com/rss2",
"description": ""
}
},
"updated": "2012-03-22T11:19:18+01:00",
"id": "https://meta.meta03.rambla.be/vocab/monty/rss/"
},
{
"content": {
"params": {
"name": "media",
"xml_namespace": "http://search.yahoo.com/mrss/",
"description": ""
}
},
"updated": "2012-03-21T12:09:46+01:00",
"id": "https://meta.meta03.rambla.be/vocab/monty/media/"
}],
"updated": "2012-03-22T11:19:18+01:00",
"link": [{
"href": "https://meta.meta03.rambla.be/vocab/monty/",
"type": "application/json",
"rel": "self"
}],
"id": "https://meta.meta03.rambla.be/vocab/monty/"
},
"version": "1.0",
"encoding": "UTF-8"
}
POST
POST http://meta.meta03.rambla.be/vocab/{username}/
= create a new vocabulary.
POST http://meta.meta03.rambla.be/vocab/{username}/{vocab}/
= overwrite the data for an existing vocabulary.
The request's body should contain an object containing the required 'vocab' params: 'name' and 'xml_namespace'. For example, if user 'monty' wanted to created the Dublin Core vocabulary, he could send a HTTP POST request to http://meta.meta01.rambla.be/vocab/monty/:
{
"entry": {
"content": {
"params": {
"name": "dc",
"xml_namespace": "http://purl.org/dc/elements/1.1/",
}
},
},
}
An update request can be sent to change the 'xml_namespace' of an existing vocab. Note that you can not update the name of the vocab instance.
DELETE
http://meta.meta03.rambla.be/vocab/{username}/{vocab}/
Deletes an existing vocab. Warning: this will also delete all meta resource and elements belonging to this vocabulary !
When successful, the response will have a HTTP status code of 204 and no body.
