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:

http

GET /plone/@vocabularies HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@vocabularies -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@vocabularies Accept:application/json -a admin:secret

python-requests

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.

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes Accept:application/json -a admin:secret

python-requests

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:

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' Accept:application/json -a admin:secret

python-requests

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:

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' Accept:application/json -a admin:secret

python-requests

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.