Server 5

Content API Guide (part of Sophora Server)

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

Getting Started

The Content API in the Sophora Server is accessible via HTTP and HTTPS. All types of Sophora Servers 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 users can assess this API with their normal password.

Swagger Example Documentation

Have a look at the Swagger documentation of Sophora's Content API. It looks like this:

Sophora Content API: Swagger Docs (Demosite)
Sophora Content API: Swagger Docs (Demosite) (Image: subshell/CC BY)

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

The following endpoints are just brief examples. The Content API additionally offers endpoints to retrieve document summaries or the published state of documents (or their summaries). Please refer to the Content API's web based Swagger documentation to view the full list of available endpoints in your server's Content API.

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 structure nodes 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. The API endpoint where the External ID is passed as a part of the url path does not support slashes in the External ID. If your External IDs contain slashes please use the same-named query parameter externalId instead.
  • Example with path variable: http://server.domain.com:1196/content-api/documentByExternalId/my-external-id
  • Example with query parameter: http://server.domain.com:1196/content-api/documentByExternalId?externalId=my-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 Sophora 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

Last modified on 10/16/20

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.

Icon