Sophora Content API

With the Content API developers can retrieve content from Sophora in JSON format via HTTP. Write and edit operations are also possible.

Table of Contents

Getting Started

The Content API in Sophora's server is accessible via HTTP and HTTPS. All types of Sophora server (master, replication slave or staging slave) are able to respond to requests.

The base url for all URLs is: http://hostname:1196/content-api

The port can be configured with the property: sophora.remote.api.http.port

All responses of requests are in JSON format.

Authentication

To access the Content API a HTTP basic authentication with user name and password is required. All Sophora user can assess this API with their normal password.

Swagger Example Documentation

Have a look at the Swagger documentation of Sophora's Content API running in the Sophora's Demo Website.

URL: http://cmsdemo.sophoracms.com/content-api/api-ui/index.html

Authentication: guest/guest

Sophora Content API: Swagger Docs (Demosite)

Configuration

The Content-API is configured in the file content-api.properties, which must be located in the folder ${sophora.home}/config. A changed configuration is at first effective after a restart of the application.

content-api.properties
Configuration KeyDescriptionDefault
content-api.client.documentCacheSizeDefines the size of the document cache. The Content-API internally maintains one Sophora Client and therefore one individual document cache for each logged in user. By choosing the size of the document cache, the estimated number of concurrently logged in users must be considered.50
content-api.textlinks.includeReferenceIs relevant for the http endpoints underneath the path /content/.

If switched to true, the Content-API URLs of referenced documents within a text link are additionally added to the corresponding anchor html element.
false
content-api.baseUrlIs only relevant for the http endpoints underneath the path /content/.

Defines the external URL of the Content-API. The configuration parameter is used for the url of referenced documents within anchor elements of text links. It is only relevant if content-api.textlinks.includeReference is set to true.
Take the configuration http://my.server.domain:1196/content-api as an example. The generated anchor element of a text link would be: <a data-reference-url="http://my.server.domain:1196/content-api/content/document/50fc8c22-56d1-4155-885a-19fb0790e6f1 ... \> ... </a>
(Empty String)
content-api.isLiveIs only relevant for the http endpoints underneath the path /content/.

Defines whether the Content-API is used for a live or preview delivery. If set to true, time schedules and offline documents are regarded. Otherwise not (due to preview).
false
content-api.domainIs only relevant for the http endpoints underneath the path /content/.

Defines the domain of the href urls of anchor elements of text links.
Take the configuration my.domain.de as an example. The generated anchor element of a text link would be: <a href="http://my.domain.de/demosite/trendcities/hamburg/hamburg100.html" ... > ... </a>
(Empty String)

Examples of the HTTP Endpoints

Please refer the swagger documentation for an comprehensive overview of the provided HTTP endpoints.

Accessing and browsing documents

URLDescription
GET /browse/{structure/node/path}To browse through documents you need to set the structurenodepath to the url. It will return all documents and structurenodes under the given path. It will not return documents and structurenodes recursively.
GET /document/{uuid}This url needs the documents uuid. It will return the document with the uuid.
GET /documentBySophoraId/{sophoraId}This url needs the Sophora-Id. It will return the document with the Sophora-Id.
GET /documentByExternalId/{externalId}This url needs the External-Id. It will return the document with the External-Id.

Browsing documents

Resource URL: http://server.domain.com:1196/content-api/browse/{StructureNodePath}

ParameterDefaultDescriptionExample
searchValue*search termsearchValue=bread
searchFieldFind the search term in the given searchFieldsearchField=fieldA&searchField=fieldB
solrSearchFieldssearchField_t:, copytext_t:, childnode_content_t:Find the given search term in the given solrSearchFieldssolrSearchFields=fieldA&solrSearchFields=fieldB
pageIndex0The pageIndex starts with an index 0pageIndex=1
pageSize1000The pageSize is the number of documents per pagepageSize=10
sortFieldTo order the result set a field to ordersortField=sophora:createdBy
sortDirectionascSets the direction of the order ascending or descending. Valid values are asc and desc. If an invalid value was set the order is ascsortDirection=desc

The example response looks like this:

{
   "totalEntriesCount": 15,
   "pageCount": 1,
   "pageIndex": 0,
   "pageSize": 1000,
   "documents": [
      {
         "jcr:primaryType": "sophora-content-nt:audio",
         "jcr:uuid": "bd774658-f980-4ad2-a17e-04572aeb0286",
         "_structureNodePath": "/demosite",
         "_url": "http://trunk.subshell.com:1196/content-api/document/bd774658-f980-4ad2-a17e-04572aeb0286",
         "_structureNodeUrl": "http://trunk.subshell.com:1196/content-api/structure/demosite",
         "isDocumentSummary": true,
         "sophora-content:shorttext": "Karl Lagerfeld's Sewing Machine ...",
         "sophora-content:taxo": [
            "Karl Lagerfeld"
         ],
         "sophora-content:title": "Sewing Machine",
         "sophora-content:topline": "Karl Lagerfeld:",
         "sophora:createdBy": "admin",
         "sophora:creationDate": "2010-06-29T11:18:00.648Z",
         "sophora:externalId": "944b4059-5b88-4088-93ed-f0b93121cdec",
         "sophora:id": "audio100",
         "sophora:isOnline": true,
         "sophora:liveStructureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:modificationDate": "2014-08-28T09:46:43.530Z",
         "sophora:modifiedBy": "admin",
         "sophora:publicationDate": "2014-08-28T09:46:43.530Z",
         "sophora:publishedBy": "admin",
         "sophora:site": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:state": "published",
         "sophora:structureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:tags": "lagerfeld sewing machine audio"
      }
   ],
   "structure": {
      "path": "demosite",
      "structure": [
         {
            "name": "home",
            "uuid": "c7ad6486-b35b-4e16-9cec-c3b26332580d",
            "hasChildren": false
         },
         {
            "name": "trendcities",
            "uuid": "05621d7b-585d-471d-8604-538c0b315880",
            "hasChildren": true
         },
         {
            "name": "forecasts",
            "uuid": "e40a400a-38d9-4b3b-95b6-2de2a1228892",
            "hasChildren": true
         },
         {
            "name": "timeline",
            "uuid": "4e543a81-48c1-4622-b03f-690da3490cf3",
            "hasChildren": false
         },
         {
            "name": "video",
            "uuid": "d7bf6ab7-d248-4ab8-9955-134c2098ce27",
            "hasChildren": false
         }
      ]
   }
}

Accessing a document

Example URL:
http://server.domain.de:1196/content-api/documentBySophoraId/test106

The response looks like this:

{
     "jcr:primaryType": "sophora-content-nt:story",
     "jcr:uuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
     "jcr:mixinTypes": [
        "sophora-content-mix:twitter",
        "sophora-content-mix:googleAdsense",
        "sophora-content-mix:documentTimingActionExtension",
        "sophora-mix:document"
    ],
    "sophora:createdBy": "admin",
    "sophora:creationDate": "2013-02-22T08:53:31.139Z",
    "sophora:externalId": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "sophora:id": "test106",
    "sophora:modificationDate": "2013-02-22T08:53:31.139Z",
    "sophora:modifiedBy": "admin",
    "sophora:originalDocument": "a7e6ec4e-9f7b-4b8d-a296-1ab177930400",
    "sophora:site": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
    "sophora:state": "inProcess",
    "sophora:structureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
    "sophora:tags": "kopie kopie kopie",
    "sophora-content:copytext": {
        "jcr:primaryType": "sophora-extension-nt:copytext",
        "sophora-extension:paragraph": {
            "jcr:primaryType": "sophora-extension-nt:paragraph",
            "sophora-extension:style": "paragraph",
            "sophora-extension:text": "",
            "sophora:childNodeId": -8701503074510348000
        }
    }
}

Saving a Document

Example URL (Method: POST):
http://server.domain.de:1196/content-api/document?idStem=test

The request parameter idStem is optional. The document to be saved must be passed as the request body in the json format.

Accessing and manipulating Structurenodes

URLDescription
POST /structure/{structurepath}Creates a new structurenode under the given path
GET /structure/{structurepath}Returns all structurenodes under the given path. It does not return structurenodes recursively
DELETE /structure/{uuid}Deletes the structurenode with the given uuid

Lock State

It is possible to access the lock state of a document. This is possible by adding /lockState to the three types of document URLs:

  • /content-api/document/{uuidStr}/lockState
  • /content-api/documentBySophoraId/{sophoraId}/lockState
  • /content-api/documentByExternalId/{externalId}/lockState

The JSON response for a locked document looks like this:

{
    "documentUuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "locked": true,
    "lockedBy": "admin",
    "lockDate": 1362054047011,
    "lockOwnerClientId": "90c33a40-7855-4fb4-9b58-7558ed42ea64"
}

The JSON response for a document without a lock looks like this:

{
    "documentUuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "locked": false
}

Nodetype Configurations

Example Url:
http://server.domain.com:1196/content-api/nodetypeByName/{nodetypename}

List of all connected servers

Example Url:
http://server.domain.com:1196/content-api/servers

List of all connected tools

Example Url:
http://server.domain.com:1196/content-api/tools