KMSREST public API

On this page:


Overview

The KMSREST public API is a RESTful API for viewing public documents from the IU Knowledge Base without need for a KMS-provisioned user account, or other authentication. The API supports viewing full documents or document fragments by ID, and searching for document sets by KM staff-defined keyterms metadata.

Note:
UITS Knowledge Management maintains all content in the KMS, and also manages the user accounts for the standard API. Because of this, the team can anticipate the needs and potential effects on these users when content changes.

However, if you use the public API, you may not be warned in advance when documents are modified, archived, or removed. This is especially true when applications access specific documents, rather than retrieve documents by semantic keyterms.

Resources

Documents

The API allows a GET request to view a public IU Knowledge Base document.

  • An origin header is required for all requests.
  • For client-side caching, use conditional headers.

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/kmst' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "docid": "kmst",
    "title": "KMS public API test document",
    "visibility": "nosearch",
    "xhtml": "<?xml version=\"1.0\" encoding=\"US-ASCII\"?>\n<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.1//EN\" \"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd\">\n<html xmlns=\"http://www.w3.org/1999/xhtml\">\n\n<head>\n \n \n        \n<meta content=\"1970-01-01T00:00:00.000-05:00\" name=\"approved-date\"/>\n<meta content=\"default\" name=\"audiences\"/>\n<meta content=\"2018-10-01T11:48:33-04:00\" name=\"last-modified\"/>\n<meta content=\"kmst\" name=\"docid\"/>\n<title>KMS public API test document</title>\n<meta content=\"sckb\" name=\"owner\"/>\n</head>\n\n<body><h1>KMS public API test document</h1>\n\n\n <div id=\"first\">\n\n  <h2>First section</h2>\n\n  <p>Lorem ipsum dolor sit amet, in quo tempor maiorum.</p>\n\n  </div>\n\n  <div id=\"second\">\n\n  <h2>Second section</h2>\n\n  <p>Ad est vivendo splendide, ad mea reque indoctum cotidieque, postea abhorreant mea ne.</p>\n\n </div>\n\n</body>\n\n</html>"
}

Fragments

To retrieve all document fragments with an id from a public document, use projection=fragments.

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/kmst?projection=fragments' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "docid": "kmst",
    "title": "KMS public API test document",
    "visibility": "nosearch",
    "fragments": [
        {
            "fragmentId": "first",
            "fragment": "<div id=\"first\">\n\n  <h2>First section</h2>\n\n  <p>Lorem ipsum dolor sit amet, in quo tempor maiorum.</p>\n\n  </div>"
        },
        {
            "fragmentId": "second",
            "fragment": "<div id=\"second\">\n\n  <h2>Second section</h2>\n\n  <p>Ad est vivendo splendide, ad mea reque indoctum cotidieque, postea abhorreant mea ne.</p>\n\n </div>"
        }
    ]
}

To retrieve a specific document fragment from a public document by its id, add the id to the URI.

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/kmst/first' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "docid": "kmst",
    "fragmentId": "first",
    "title": "KMS public API test document",
    "visibility": "nosearch",
    "fragment": "<div id=\"first\">\n\n  <h2>First section</h2>\n\n  <p>Lorem ipsum dolor sit amet, in quo tempor maiorum.</p>\n\n  </div>"
}

Keyterms search

To find all documents with a specific keyterm metadata, use metadata?keyterms=value.

Multiple comma-separated values are allowed; documents that have multiple requested keyterms will be returned once, with all keyterm information.

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/metadata?keyterms=test1,test2' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "documentMetadata": [
        {
            "title": "KMS public API test document",
            "docid": "kmst",
            "keyterms": [
                {
                    "type": "about",
                    "keyterm": "test1"
                },
                {
                    "type": "getstarted",
                    "keyterm": "test2"
                }
            ]
        }
    ]
}

Keyterms type

The keyterms type provides semantic information about a document, in combination with its keyterm(s). To find all documents of a specific type for a given keyterm, use metadata?keyterms=value&type=typevalue. Multiple comma-separated values for type are also allowed

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/metadata?keyterms=test1,test2&types=about,getstarted' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "documentMetadata": [
        {
            "title": "KMS public API test document",
            "docid": "kmst",
            "keyterms": [
                {
                    "type": "about",
                    "keyterm": "test1"
                },
                {
                    "type": "getstarted",
                    "keyterm": "test2"
                }
            ]
        }
    ]
}

Documents will only be found if a type is associated with a given keyterm; if the type is associated with a different keyterm in the document, it will not match.

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/metadata?keyterms=test1,test2&types=about' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "documentMetadata": [
        {
            "title": "KMS public API test document",
            "docid": "kmst",
            "keyterms": [
                {
                    "type": "about",
                    "keyterm": "test1"
                },
            ]
        }
    ]
}

Example request:

curl 'https://rest.kb.iu.edu/v1/documents/metadata?keyterms=test2&types=about' -H "Origin: https://yoursite.iu.edu" -i

Example response:

{
    "documentMetadata": []
}

Cache documents or fragments

When caching documents or document fragments, save either the ETag or Last-Modified response header value for the record locally. When retrieving the document or fragment again, provide the saved values in their respective conditional request headers to determine if it has been updated:

ETag: If-None-Match

The API will only fetch the document if the value of its ETag does not match the value of the If-None-Match header. If the value of the header matches the value of the ETag, meaning nothing has changed, the API will return an HTTP 304 Not Modified status code.

Example request:

$ curl 'https://rest.kb.iu.edu/v1/documents/kmst' -H "Origin: https://yoursite.iu.edu" -i \
    -H 'If-None-Match: "0"'

Example response:

HTTP/1.1 304 Not Modified
ETag: "0"
Last-Modified: Wed, 01 Oct 2018 15:48:31 GMT

Last-Modified: If-Modified-Since

The API will only fetch the document if it has changed since the time provided in the If-Modified-Since header (in RFC_1123 format; e.g., Mon, 01 Oct 2018 18:13:37 GMT). If the resource has changed, the API will return an updated Last-Modified response header. If not, it will return an HTTP 304 Not Modified status code:

Example request:

$ curl 'https://rest.kb.iu.edu/v1/documents/kmst' -H "Origin: https://yoursite.iu.edu" -i \
    -H 'If-Modified-Since: Mon, 01 Oct 2018 18:13:37 GMT'

Example response:

HTTP/1.1 304 Not Modified
ETag: "0"
Last-Modified: Mon, 01 Oct 2018 15:48:31 GMT

This is document atln in the Knowledge Base.
Last modified on 2018-12-18 12:41:22.

Contact us

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