Vocabularies¶
Vocabularies are utilities containing a list of values grouped by interest or different Plone features.
For example, plone.app.vocabularies.ReallyUserFriendlyTypes
will return all the content types registered in Plone.
The vocabularies return a list of objects with the items title
and token
.
Note
These docs are generated by code tests, therefore you will see some ‘test’ contenttypes appear here.
Get all vocabularies¶
To retrieve a list of all the available vocabularies, send a GET request to the @vocabularies endpoint:
GET /plone/@vocabularies HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i http://nohost/plone/@vocabularies -H 'Accept: application/json' --user admin:secret
http http://nohost/plone/@vocabularies Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@vocabularies', headers={
'Accept': 'application/json',
}, auth=('admin', 'secret'))
The response will include a list with the URL (@id
) the dotted names (title
) of all the available vocabularies in Plone:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes",
"title": "plone.app.vocabularies.ReallyUserFriendlyTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableContentLanguages",
"title": "plone.app.vocabularies.AvailableContentLanguages"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.schemaeditor.VocabulariesVocabulary",
"title": "plone.schemaeditor.VocabulariesVocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.users.group_ids",
"title": "plone.app.users.group_ids"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Permissions",
"title": "plone.app.vocabularies.Permissions"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.contentrules.events",
"title": "plone.contentrules.events"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.CaptchaVocabulary",
"title": "plone.app.discussion.vocabularies.CaptchaVocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Actions",
"title": "plone.app.vocabularies.Actions"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ImagesScales",
"title": "plone.app.vocabularies.ImagesScales"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.PortalActionCategories",
"title": "plone.app.vocabularies.PortalActionCategories"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.vocabularies.AllAvailableLanguageVocabulary",
"title": "plone.app.multilingual.vocabularies.AllAvailableLanguageVocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.RootCatalog",
"title": "plone.app.multilingual.RootCatalog"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.content.ValidAddableTypes",
"title": "plone.app.content.ValidAddableTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.CommonTimezones",
"title": "plone.app.vocabularies.CommonTimezones"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.restapi.testing.context_vocabulary",
"title": "plone.restapi.testing.context_vocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableEditors",
"title": "plone.app.vocabularies.AvailableEditors"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Roles",
"title": "plone.app.vocabularies.Roles"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages",
"title": "plone.app.vocabularies.SupportedContentLanguages"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Keywords",
"title": "plone.app.vocabularies.Keywords"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Groups",
"title": "plone.app.vocabularies.Groups"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableTimezones",
"title": "plone.app.vocabularies.AvailableTimezones"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog",
"title": "plone.app.vocabularies.Catalog"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.TextTransformVocabulary",
"title": "plone.app.discussion.vocabularies.TextTransformVocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Month",
"title": "plone.app.vocabularies.Month"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Weekdays",
"title": "plone.app.vocabularies.Weekdays"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WorkflowTransitions",
"title": "plone.app.vocabularies.WorkflowTransitions"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WeekdaysShort",
"title": "plone.app.vocabularies.WeekdaysShort"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.contenttypes.metadatafields",
"title": "plone.app.contenttypes.metadatafields"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/Interfaces",
"title": "Interfaces"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WorkflowStates",
"title": "plone.app.vocabularies.WorkflowStates"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/Fields",
"title": "Fields"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.contenttypes.migration.atctypes",
"title": "plone.app.contenttypes.migration.atctypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.vocabularies.AllContentLanguageVocabulary",
"title": "plone.app.multilingual.vocabularies.AllContentLanguageVocabulary"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SyndicatableFeedItems",
"title": "plone.app.vocabularies.SyndicatableFeedItems"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AllowedContentTypes",
"title": "plone.app.vocabularies.AllowedContentTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.users.user_registration_fields",
"title": "plone.app.users.user_registration_fields"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WeekdaysAbbr",
"title": "plone.app.vocabularies.WeekdaysAbbr"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.UserFriendlyTypes",
"title": "plone.app.vocabularies.UserFriendlyTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.PortalTypes",
"title": "plone.app.vocabularies.PortalTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/Behaviors",
"title": "Behaviors"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SyndicationFeedTypes",
"title": "plone.app.vocabularies.SyndicationFeedTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Timezones",
"title": "plone.app.vocabularies.Timezones"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.formwidget.relations.cmfcontentsearch",
"title": "plone.formwidget.relations.cmfcontentsearch"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Skins",
"title": "plone.app.vocabularies.Skins"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AllowableContentTypes",
"title": "plone.app.vocabularies.AllowableContentTypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.contenttypes.migration.extendedtypes",
"title": "plone.app.contenttypes.migration.extendedtypes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.MonthAbbr",
"title": "plone.app.vocabularies.MonthAbbr"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Workflows",
"title": "plone.app.vocabularies.Workflows"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.contenttypes.migration.changed_base_classes",
"title": "plone.app.contenttypes.migration.changed_base_classes"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users",
"title": "plone.app.vocabularies.Users"
},
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.event.SynchronizationStrategies",
"title": "plone.app.event.SynchronizationStrategies"
}
]
Get a vocabulary¶
To get a particular vocabulary, use the @vocabularies
endpoint with the name of the vocabulary, e.g. /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes
.
The endpoint can be used with the site root and content objects.
GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes -H 'Accept: application/json' --user admin:secret
http http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes', headers={
'Accept': 'application/json',
}, auth=('admin', 'secret'))
The server will respond with a list of terms. The title is purely for display purposes. The token is what should be sent to the server to retrieve the value of the term.
Note
Vocabulary terms will be batched if the size of the resultset exceeds the batch size. See Batching for more details on how to work with batched results.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes",
"items": [
{
"title": "Collection",
"token": "Collection"
},
{
"title": "Comment",
"token": "Discussion Item"
},
{
"title": "DX Test Document",
"token": "DXTestDocument"
},
{
"title": "Event",
"token": "Event"
},
{
"title": "File",
"token": "File"
},
{
"title": "Folder",
"token": "Folder"
},
{
"title": "Image",
"token": "Image"
},
{
"title": "Link",
"token": "Link"
},
{
"title": "News Item",
"token": "News Item"
},
{
"title": "Page",
"token": "Document"
},
{
"title": "Test Document",
"token": "ATTestDocument"
},
{
"title": "Test Folder",
"token": "ATTestFolder"
}
],
"items_total": 12
}
Filter Vocabularies¶
Vocabulary terms can be filtered using the title
or token
parameter.
Use the title
paramenter to filter vocabulary terms by title.
E.g. search for all terms that contain the string doc
in the title:
GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' -H 'Accept: application/json' --user admin:secret
http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc', headers={
'Accept': 'application/json',
}, auth=('admin', 'secret'))
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc",
"items": [
{
"title": "DX Test Document",
"token": "DXTestDocument"
},
{
"title": "Test Document",
"token": "ATTestDocument"
}
],
"items_total": 2
}
Use the token
paramenter to filter vocabulary terms by token.
This is useful in case that you have the token and you need to retrieve the title
.
E.g. search the term doc
in the token:
GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' -H 'Accept: application/json' --user admin:secret
http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' Accept:application/json -a admin:secret
requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document', headers={
'Accept': 'application/json',
}, auth=('admin', 'secret'))
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document",
"items": [
{
"title": "Page",
"token": "Document"
}
],
"items_total": 1
}
Note
You must not filter by title and token at the same time. The API returns a 400 response code if you do so.