KMSREST standard API

On this page:


Overview

The KMSREST standard API is a RESTful API for searching and viewing documents from the IU Knowledge Management System. The API supports viewing documents by ID and searching for documents by full-text Solr search.

Resources

Documents

Request

KMSREST document view is a GET request at:

  /v0/document/$docid.(json|xhtml)

$docid is the document ID. It requires Basic Authentication (BasicAuth); pass credentials in the URL or via the Basic header.

The request is the same for both the test and production environments:

  https://rest-test.kb.iu.edu/
  https://rest.kb.iu.edu/
Note:
A request can use either headers or query string parameters or a mixture to pass parameters.
Headers Query string parameters
Accept: Pass the media type you wish returned. Accepted values are application/xhtml+xml and application/json
N/A
Use GET: /v0/document/$docid.json
or GET: /v0/document/$docid.xhtml

Response

  • Requesting a plain XHTML response using Accept: application/xhtml+xml returns a valid XHTML document.
  • Requesting a JSON response wrapper using Accept: application/json returns a JSON object. Example:
    {
       "status": "ok",
       "message": "A MESSAGE",
       "content": "THE XHTML DOCUMENT",
       "version": "THE API VERSION",
       "timestamp": "THE CURRENT TIMESTAMP"
    }
  • Response fields:
    • status: May be "ok" or "error"
    • message: A simple message indicating the outcome of the response
    • content: The document in XHTML format
    • version: The REST API version requested
    • timestamp: The current timestamp of the request
    • stack: Returned on error when a stack trace is available

Request

KMSREST document search is a GET request at:

  /v0/search.json

It requires Basic Authentication (BasicAuth); pass credentials in the URL or via the Basic header.

The request is the same for both the test and production environments:

  https://rest-test.kb.iu.edu/
  https://rest.kb.iu.edu/
Note:
A request can use either headers or query string parameters or a mixture to pass parameters.
Headers Query string parameters
Accept: Must be set to application/json (required only if using HTTP headers for requests)
N/A
Use GET: /v0/search.json
X-Kms-Page: This is used for paging results. Starts on page 0. The response returns some useful elements for paging such as totalPages, totalElements, etc. (defaults to 0)
page
e.g., page=1
X-Kms-Page-Size: This indicates the number of results to be returned in a response. Limit this on the server side. (defaults to 15; max size is 300)
pageSize
e.g., pageSize=15
X-Kms-Q: The search query (required)
q
e.g., q=Outlook
X-Kms-Show-Archived: (Optional) Returns results including archived documents at the bottom. Value: yes or no, defaults to no.
showArchived
e.g., showArchived=yes

Response

  • JSON is the only supported response. Requesting a JSON response using Accept: application/json returns a JSON object. Example:
    {
       "status":"ok",
       "message":"Searched successfully.",
       "content":{
          "pagedDocuments":{
             "content":[
                {
                   "docid":"axig",
                   "title":"IU Secure wireless connections: Linux",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1396929600000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1216094400000,
                   "approvedDate":1396929600000,
                   "owner":"sct2-dsm"
                },
                {
                   "docid":"awws",
                   "title":"About IU Secure wireless",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1399608000000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1209614400000,
                   "approvedDate":1381982400000,
                   "owner":"cne"
                },
                {
                   "docid":"baxg",
                   "title":"IU Secure wireless connections:\n BlackBerry PlayBook",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1392181200000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1305864000000,
                   "approvedDate":1392181200000,
                   "owner":"sctier2"
                },
                {
                   "docid":"axsw",
                   "title":"IU Secure wireless connections: openSUSE",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1396929600000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1225339200000,
                   "approvedDate":1396929600000,
                   "owner":"sctier2"
                },
                {
                   "docid":"axsv",
                   "title":"IU Secure wireless connections: Fedora",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1396929600000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1225339200000,
                   "approvedDate":1396929600000,
                   "owner":"sctier2"
                },
                {
                   "docid":"azle",
                   "title":"IU Secure wireless connections: Android\n OS",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1403064000000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1266382800000,
                   "approvedDate":1393477200000,
                   "owner":"sctier2"
                },
                {
                   "docid":"axsu",
                   "title":"IU Secure wireless connections: Ubuntu",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1396929600000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1225339200000,
                   "approvedDate":1396929600000,
                   "owner":"sctier2"
                },
                {
                   "docid":"ayax",
                   "title":"IU Secure wireless connections: Windows",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1402459200000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1231477200000,
                   "approvedDate":1402459200000,
                   "owner":"scfl"
                },
                {
                   "docid":"axfh",
                   "title":"At IU, how do I use the secure server on Pages?",
                   "audiences":[
                      "default"
                   ],
                   "lastModified":1389330000000,
                   "visibility":"visible",
                   "importance":"standard",
                   "birthDate":1214193600000,
                   "approvedDate":1335240000000,
                   "owner":"webtech"
                }
             ],
             "facetResultPages":[
    
             ],
             "facetQueryResult":{
                "content":[
    
                ],
                "sort":null,
                "numberOfElements":0,
                "totalElements":0,
                "totalPages":1,
                "firstPage":true,
                "lastPage":true,
                "size":0,
                "number":0
             },
             "highlighted":[
    
             ],
             "facetFields":[
    
             ],
             "allFacets":[
                null
             ],
             "sort":null,
             "numberOfElements":10,
             "totalElements":416,
             "totalPages":42,
             "firstPage":true,
             "lastPage":false,
             "size":10,
             "number":0
          },
          "suggestions":[
    
          ]
       },
       "version":0,
       "timestamp":"2014-07-30 15:37:10"
    }
  • Response fields:
    • status: May be "ok" or "error"
    • message: A simple message indicating the outcome of the response
    • content: A Solr page response. It itself contains a content object. The Solr content object contains an array of documents returned. Currently the fields for each document returned are: docid, title, audiences, lastModified, visibility, importance, birthDate, approvedDate and owner. In addition to content are paging fields: size (the page size you requested), number (the current page starting from 0), numberOfElements (the number of elements returned in the page), sort (the sorting direction), totalPages (the total number of pages for the request), totalElements (the total number of elements returned for the entire request), firstPage (Boolean to indicate if you're on the first page of the results), lastPage (Boolean to indicate if you're on the last page of the results).
    • version: The REST API version requested
    • timestamp: The current timestamp of the request

Sitemap

Request

KMSREST sitemap is available by GET request at:

  /v0/sitemap.xml

It requires Basic Authentication (BasicAuth); pass credentials in the URL or via the Basic header.

The request is the same for both the test and production environments:

  https://rest-test.kb.iu.edu/
  https://rest.kb.iu.edu/
Note:
A request can only use headers to pass parameters.
Headers
X-Kms-Base-Url: Pass the valid base URL to documents (e.g., kb.iu.edu/d/)

Response

Requesting a plain XML response using Accept: application/xml returns a valid XML document.

Caching documents

Every time a document is updated, the KMS generates a new UUID for it; when caching documents, retrieve and save the document's UUID. When retrieving the document again, ompare the UUID of the cached version to the UUID of the live version to check if the cached version is out of date.

To get the UUID, make a GET request to:

  /v0/document/uuid/$docid

$docid is the document ID.

The request requires basic access authentication; pass credentials in the URL or via the Basic HTTP header.

The response will be a JSON object, e.g.:

{
   "status": "ok",
   "message": "Document retrieved successfully.",
   "uuid": "7e9de5a7-2b4f-4a39-9399-87cdfee44517",
   "version": 0,
   "timestamp": "2016-02-26T15:28:08.201-05:00"
}

This is document atrr in the Knowledge Base.
Last modified on 2018-11-13 13:38:37.

Contact us

For help or to comment, email the UITS Support Center.