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:
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.
| Configuration Key | Description | Default |
|---|---|---|
| content-api.client.documentCacheSize | Defines 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.includeReference | Is 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.baseUrl | Is 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.isLive | Is 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.domain | Is 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
| URL | Description |
|---|---|
| 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.
|
Browsing documents
Resource URL: http://server.domain.com:1196/content-api/browse/{StructureNodePath}
| Parameter | Default | Description | Example |
|---|---|---|---|
| searchValue | * | search term | searchValue=bread |
| searchField | Find the search term in the given searchField | searchField=fieldA&searchField=fieldB | |
| solrSearchFields | searchField_t:, copytext_t:, childnode_content_t: | Find the given search term in the given solrSearchFields | solrSearchFields=fieldA&solrSearchFields=fieldB |
| pageIndex | 0 | The pageIndex starts with an index 0 | pageIndex=1 |
| pageSize | 1000 | The pageSize is the number of documents per page | pageSize=10 |
| sortField | To order the result set a field to order | sortField=sophora:createdBy | |
| sortDirection | asc | Sets the direction of the order ascending or descending. Valid values are asc and desc. If an invalid value was set the order is asc | sortDirection=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
| URL | Description |
|---|---|
| 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}
