Documentation Center

Content Service API

An exhaustive list of the API for the Content Service, which is a partial implementation of the OData protocol.

Retrieving Item Type collections

The Content Service root URL is http://HOST:PORT/content.svc/, where HOST:PORT identifies the base URL of the Content Service.

You can get the following item type collections:
  • /Binaries
  • /BinaryVariants
  • /ComponentPresentations
  • /Components
  • /CustomMetas
  • /Keywords
  • /PageContents
  • /Pages
  • /Publications
  • /Schemas
  • /StructureGroups
  • /Templates

Retrieving specific items

To retrieve a specific Publication, add /Publications(<PubID>) or /Publications(Id=<PubID>) to the root URL, where <PubID> is the number ID of the Publication you want to retrieve.

You can append any of the other item types to this URL to retrieve all items of that type within the Publication; for example, appending /Publications(3)/Binaries to the root URL gets all binaries in the Publication with ID 3).

To retrieve a specific item, specify ItemId and PublicationId parameters for an item type. For example, /Components(ItemId=12, PublicationId=9) retrieves the Component with ID 12 from the Publication with ID 9.

Retrieving properties

To retrieve a property of an item, add the name of that property to your specific-item query. For example, /StructureGroups(ItemId=12, PublicationId=3)/Title gets the title of the Structure Group with ID 12 in the Publication with ID 3.

Entity relationships

You can also use entity relationships between items. For example, if you have a URL that retrieves one specific Component, you can append /Schema to that URL to retrieve the Schema on which that Component is based.

The following diagrams shows the relationships between the various item types.

For example, to retrieve all Component Presentations that contain a specific Component with the ID 131 located in the Publication with ID 15, append the following to the root URL:

/Components(ItemId=131, PublicationId=15)/ComponentPresentations

And to get the Schema for that same Component, you can append the following (note the singular):

/Components(ItemId=131, PublicationId=15)/Schema

Your response from the web service contains link elements with a href attribute that specifies the relationships from the returned item to other items. For example, if a response contains items of type "Component Presentation", then link elements for the following will be included in the response:

  • A link element for the Component Presentation
  • A link element for the Component
  • A link element for the Component Template
  • A link element for Pages on which the Component Presentation occurs

You can expand these links by adding one or more $expand query parameters to your URL, set to the name of the relationship (possibly followed by a subquery for subitems or properties). With $expand set, the link elements in the response will now have contents: an <m:inline> element that contains the item(s) or property you queried in the $expand query parameters.

Paginating results

If the number of items returned is very large, you may wish to paginate your results: that is, retrieve the items that match your query in chunks. To do this, call the web service repeatedly, using the following query parameters:

$top
Specifies the maximum number of items to return from this call (your 'page size').
$skip
Specifies the number of items to skip (this is always a multiple of $top).

To paginate your results in, say, chunks of 20, do the following:

  1. On your first call, append ?$top=20 to your URL ($skip is initially 0 and can therefore be omitted).
  2. On your second call, append ?$top=20&$skip=20
  3. On your third call, append ?$top=20&$skip=40
  4. Continue to update the value of $skip as required.

Return format

Depending on your query, the Content Service returns an XML document with one of the following structures:

  • A single <entry> element, if your query returned a single item.
  • An single element that has the name of a property (e.g. <Title>), if your query returned a single property.
  • A <feed> element containing one or more <entry> elements.

The <entry> element in the response contains the item itself. The exact XML differs depending on the type of item you are retrieving. To see the XML structure for each item type, add /$metadata to the web service root URL.

You can also get your response in JSON format by appending the query parameter $format="json" to the end of your URL. For example:

http://HOST:PORT/content.svc/Pages(ItemId=6,PublicationId=3)?$format=json