Content APIs

Get Content List

OVERVIEW

Overview

This API call is used to retrieve content list from Publisher.

Requests are made via POST to enable complexity of the request, with complex and/or filtering being available for metadata queries

Since v5.1

HTTP Request

POST  /api/2/content

HTTP Request Object

Content search request object either in JSON or XML format.

HTTP Headers
HTTP Request Header Description Example
Authorization The API Authorisation token "Bearer XXXXXXXXXXXXX"
Accept

The format of the expected response. 

  • "application/json"
  • "application/xml"

If no parameter is set, JSON is the default response given.

 "application/xml"
Content-Type

The format of the provided content.

  • "application/json"
  • "application/xml"

If no parameter is set, JSON is the expected content by default.

 "application/json"

 

API Accessibility

Access Type Description
API Token without user parameter Super admin, system admin, campaign admin, internal system admin, channel admin and editor can access the API.
API Token of System Admin with user parameter If API token is of system admin then 'user' parameter can be passed, allowing to call the API on that user's behalf.
API Token of user other than System Admin with user parameter

Not allowed and results in below with response code 400

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>108</ref>
    <summary>The requested user does not exist</summary>
</error>

 

Parameter details

Parameter Description Example
user User email on behalf of whom the api called.   "user": "ua@mi.com"
limit Maximum number of results to fetch. Default value is 30.  "limit": "7"
offset Page number. Default value is 0.  "offset": "0"
search Search content titles by this keyword  "search": "Home"
sort

Allow ascending and descending sorting for a single field.

  •  +/-recent: will sort based on the date the content was last modified.
  •  +/-mostviewed: will sort based on the number of views of content.
  • +/-alphabetical: will sort based on content title.
  • +/-recentbydevdate : will sort based on the development date of content.
  "sort": "+alphabetical"
language Will return publication content in the given language. If language code is not provided, then results will be shown in the user's language set in their user preferences.  "language": "en_US"
contenttypes

Filter results by their content type

  • Publications = will display publications only.
  • Videos = will display videos only.
  • Events = will display events only.
 "contenttypes" :["Publications","Videos"]
date Display results based on selected To and From date, with the format YYYYMMDD "date":{
            "from" : "20180101",
            "to" : "20180101"
        }
usedevelopmentdate When date filter is applied then it will check whether to use the published date or development date to perform the date filter. "usedevelopmentdate" : "true"
modules To filter the contents by the module. "modules" : ["HighQ Module"]
keywords To filter the contents by the keywords/tags. keywords" : ["Mkt", "IT"]
respectpreference

Below are the possible values for this parameter

  • Absence of the parameter means - no preference
  • 1/user- User Preference and
  • 2/channel- Channel Preference (channel id/name must be provided in 'respectpreferencechannel' parameter)
 "respectpreference":"2"
"respectpreference":"user"
respectpreferencechannel Channel id/name to be provided under this parameter and is only applicable when the 'respectpreferencechannel' is '2' or 'channel' "respectpreferencechannel" : "2"

 

Metadata filter parameters

Metadata filter is a logic filter, where the metadata list can be specified by 'and'/'or' operations. Below are the sample requests to filter contents with metadata.

JSON Request

{
    "contentquery":{
        "limit" : "10",
        "metadata" : {
            "and" : [
                {
                    "name" : "Density",
                    "labels" : [
                        {"name": "Low"}
                    ]
                },
                {
                    "or" :[
                        {
                            "name" : "Shape",
                            "labels" : [
                                {"name": "Circle"}
                            ]
                        },
                        {
                            "name" : "Colour",
                            "labels" : [
                                {"name": "Blue"}
                            ]
                        }
                    ]
                }
            ]
            
        }
    }    
}
XML Request <?xml version="1.0" encoding="UTF-8"?>
<contentquery>
   <metadata>
      <or>
         <metadata>
            <or>
               <metadata>
                  <name>Density</name>
                  <labels>
                     <label>
                        <name>High</name>
                     </label>
                  </labels>
               </metadata>
               <metadata>
                  <name>Colour</name>
                  <labels>
                     <label>
                        <name>Blue</name>
                     </label>
                  </labels>
               </metadata>
            </or>
         </metadata>
         <metadata>
            <name>Shape</name>
            <labels>
               <label>
                  <name>Oval</name>
               </label>
            </labels>
         </metadata>
      </or>
   </metadata>
</contentquery>


Example HTTP Request & Response

POST http://example.com/context/api/2/content

JSON Request

{  
   "contentquery":{  
      "user":"mitul.patel@highq.com",
      "language":"en_GB",
      "limit":"50",
      "offset":"0",
      "search":"a",
      "contenttypes":[  
         "Publications",
         "Events"
      ],
      "modules":[  
         "Publications"
      ],
      "keywords":[  
         "tag1",
         "tag2"
      ],
      "respectpreference" : "user",
      "respectpreferencechannel" : 2
   }
}

JSON Response

{
    "total": 1,
    "totalcount": 190,
    "currentpage": 0,
    "contentlist": [
        {
            "id": 1349,
            "author": {
                "id": 27,
                "email": "rishit.patel@highq.com",
                "organisation": {
                    "id": 1,
                    "name": "HighQ"
                },
                "firstname": "Rishit",
                "lastname": "Patel"
            },
            "icon": {
                "title": "Article",
                "iconclass": {
                    "medium": "icon-highq-publication",
                    "small": "icon-highq-publication-small"
                }
            },
            "favorite": {
                "favourited": false
            },
            "url": "https://example.com/context/pd19785_publication_module_ehzax/pd19785_content_england_india_newsouthwales_ehzax",
            "like": {
                "liked": false,
                "likes": 0
            },
            "module": {
                "id": 1322,
                "name": "PD19785_Publication_Module_ehZax",
                "url": "https://example.com/context/pd19785_publication_module_ehzax",
                "type": {
                    "id": 1,
                    "name": "Publications"
                }
            },
            "title": "PD19785_Content_England_India_NewSouthWales_ehZax",
            "readtime": 0,
            "publishdate": "19 Feb 2019 11:34",
            "numberofcomments": 0,
            "numberofviews": 10,
            "publicurl": "https://example.com/context/pd19785_publication_module_ehzax/pd19785_content_england_india_newsouthwales_ehzax?nav=FRbANEucS95NMLRN47z%2BeeOgEFCt8EGQ71hKXzqW2Ec%3D&key=BcJlhLtdCv6%2FJTDZxvL23RkMLFknecjNXt444ZucAQUoIs5EbvZ8fPT41umLaMN9%2F%2Fiv77swTfEdZmAO%2BCy5k76jfXgQS9Wb",
            "downloadurl": "https://example.com/context/dispatchContent.action?key=BcJlhLtdCv6%2FJTDZxvL23RkMLFknecjNXt444ZucAQUoIs5EbvZ8fPT41umLaMN9%2F%2Fiv77swTfEdZmAO%2BCy5k76jfXgQS9Wb&nav=FRbANEucS95NMLRN47z%2BeeOgEFCt8EGQLgG0HP2%2Bl9M%3D&pdfview=true"
        }
    ]
}

 

XML Request

<?xml version="1.0" encoding="UTF-8" ?>
<contentquery>
    <user>mitul.patel@highq.com</user>
    <language>en_GB</language>
    <limit>50</limit>
    <offset>0</offset>
    <search>a</search>
    
    <contenttypes>
        <contenttype>Publications</contenttype>
        <contenttype>Events</contenttype>
    </contenttypes>
    
    <modules>
        <module>Publications</module>
    </modules>
    
    <keywords>
        <keyword>abc</keyword>
    </keywords>
    
    <respectpreference>channel</respectpreference>
    <respectpreferencechannel>2</respectpreferencechannel>
    
</contentquery>

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contents>
    <totalcount>190</totalcount>
    <total>1</total>
    <currentpage>0</currentpage>
    <contentlist>
        <content>
            <id>1349</id>
            <title>PD19785_Content_England_India_NewSouthWales_ehZax</title>
            <readtime>0</readtime>
            <publishdate>19 Feb 2019 11:34</publishdate>
            <author>
                <id>27</id>
                <firstname>Rishit</firstname>
                <lastname>Patel</lastname>
                <email>rishit.patel@highq.com</email>
                <organisation>
                    <id>1</id>
                    <name>HighQ</name>
                </organisation>
            </author>
            <icon>
                <title>Article</title>
                <iconclass>
                    <medium>icon-highq-publication</medium>
                    <small>icon-highq-publication-small</small>
                </iconclass>
            </icon>
            <favorite>
                <favourited>false</favourited>
            </favorite>
            <url>https://example.com/context/pd19785_publication_module_ehzax/pd19785_content_england_india_newsouthwales_ehzax</url>
            <like>
                <liked>false</liked>
                <likes>0</likes>
            </like>
            <numberofcomments>0</numberofcomments>
            <numberofviews>10</numberofviews>
            <publicurl>https://example.com/context/pd19785_publication_module_ehzax/pd19785_content_england_india_newsouthwales_ehzax?nav=FRbANEucS95NMLRN47z%2BeeOgEFCt8EGQ71hKXzqW2Ec%3D&amp;key=BcJlhLtdCv6%2FJTDZxvL23RkMLFknecjNXt444ZucAQUoIs5EbvZ8fPT41umLaMN9%2F%2Fiv77swTfEdZmAO%2BCy5k76jfXgQS9Wb</publicurl>
            <downloadurl>https://example.com/context/dispatchContent.action?key=BcJlhLtdCv6%2FJTDZxvL23RkMLFknecjNXt444ZucAQUoIs5EbvZ8fPT41umLaMN9%2F%2Fiv77swTfEdZmAO%2BCy5k76jfXgQS9Wb&amp;nav=FRbANEucS95NMLRN47z%2BeeOgEFCt8EGQLgG0HP2%2Bl9M%3D&amp;pdfview=true</downloadurl>
            <module>
                <id>1322</id>
                <name>PD19785_Publication_Module_ehZax</name>
                <url>https://example.com/context/pd19785_publication_module_ehzax</url>
                <type>
                    <id>1</id>
                    <name>Publications</name>
                </type>
            </module>
        </content>
    </contentlist>
</contents>

Validation Messages
Description Response Response Code
When 'offset' is negative or not a number. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>106</ref>
    <summary>Invalid parameter: offset</summary>
</error>		 400
When 'limit' is not a positive number. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>107</ref>
    <summary>Invalid parameter: limit</summary>
</error>		 400
When  user email passed in 'user' parameter that does not exists <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>108</ref>
    <summary>The requested user does not exist</summary>
</error>		 400
When  invalid 'language' parameter is passed <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>144</ref>
    <summary>Invalid parameter: language</summary>
</error>		 400
When  invalid 'sort' parameter is passed <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>79</ref>
    <summary>Invalid parameter: sort</summary>
</error>		 400
When 'respectpreference' is invalid <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>194</ref>
    <summary>Invalid parameter: respectpreference</summary>
</error>		 400
When 'respectpreference' is set to 'channel' but no channel id or name provided in 'respectpreferencechannel'. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>195</ref>
    <summary>Channel is required</summary>
</error>		 400
When date is added but' from' and 'to' is not provided in request. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>149</ref>
    <summary>From and to date is required</summary>
</error>		 400
When 'from' date is invalid <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>145</ref>
    <summary>Invalid from date</summary>
</error>		 400
When 'to' date is invalid <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>146</ref>
    <summary>Invalid to date</summary>
</error>		 400
When 'from' date is greater than 'to' date <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>191</ref>
    <summary>From date should be less than to date</summary>
</error>		 400
When usedevelopmentdate is other than 'true' or 'false'. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>209</ref>
    <summary>Invalid usedevelopmentdate</summary>
</error>		 400
When 'respectpreference' is set to 'channel' but channel id or name provided in 'respectpreferencechannel' does not exists. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>196</ref>
    <summary>Channel does not exist</summary>
</error>		 400

When invalid metadata provided

{
        "contentquery":{
                "limit" : "10",
                "metadata" : {
                        "or" : [
                                        {"name" : "Countrie"}
                        ]
                        
                }
        }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error>
        <fieldName>metadata: Countrie</fieldName>
        <message>Metadata does not exist</message>
    </error>
</errors>		 400

When category is invalid

{
    "contentquery":{
            "limit" : "10",
            "metadata" : {
                "or" : [
                    {
                        "name" : "Countries",
                        "categories" : [
                                {
                                        "name" : "Afri"
                                }        
                        ]
                    }
                ]                    
            }
    }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error>
        <fieldName>metadata.category: Countries.Afri</fieldName>
        <message>Category does not exist</message>
    </error>
</errors>		 400

When label is invalid

{
    "contentquery":{
        "limit" : "10",
        "metadata" : {
            "or" : [
                {
                    "name" : "Countries",
                    "categories" : [
                        {
                                "name" : "Africa",
                                "labels" : [
                                        {
                                                "name" : "Nigeri"
                                        }
                                ]
                        }        
                    ]
                }
            ]
        }
    }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error>
        <fieldName>metadata.category.label: Countries.Africa.Nigeri</fieldName>
        <message>Label does not exist</message>
    </error>
</errors>		 400

When both and and or list is present under the metadata node

{
    "contentquery":{
        "limit" : "10",
        "metadata" : {
            "or" : [],
            "and" : []
        }
    }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>233</ref>
    <summary>Metadata queries must be nested, both 'and' and 'or' cannot both exist at the same level.</summary>
</error>		 400

When and/or nesting is more than 2 level

{
    "contentquery":{
        "limit" : "10",
        "metadata" : {
            "or" : [
                {
                    "or" :[
                        {
                            "or" :[
                                    {
                                    }
                            ]                                
                        }
                    ]                
                }
            ]
        }
    }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>234</ref>
    <summary>Metadata query parameters can only be nested 2 levels deep</summary>
</error>		 400

Metadata queries can not be structured as an 'and' within an 'or'

{
    "contentquery":{
        "limit" : "10",
        "metadata" : {
            "or" : [
                {
                    "and" :[
                        {
                            "name" : "Countries"
                        }
                    ]                
                }
            ]
        }
    }        
}

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <ref>235</ref>
    <summary>Metadata queries can not be structured as an 'and' within an 'or' query</summary>
</error>		 400

 

Comments


0 Comments

Last Updated: Nov 08,2024