Introduction

This is the reference document for the REST API and resources provided by Spider Knowledge Base. The REST APIs are for developers who want to integrate Spider Knowledge Base with other standalone or web applications.

Structure of the REST URIs

The REST API provide access to resources via URI paths. To use the REST API, a HTTP request has to be made and the response need to be parsed.

The REST API supports JSON as data format and the standard HTTP methods like GET, PUT, POST and DELETE.

URIs for the REST API have the following structure:
http://host.port/operationsmanager/rest/api/1/kb/model-namespace/resource-name
e.g.
http://demo.myserver.com:8080/operationsmanager/rest/api/1/kb/mykb/article/KB-00012

Authentication

The REST API support two types of authentication: HTTP Basic access authentication and HttpSession (Cookie) based authentication. The prefered way is HTTP Basic (with SSL). To use HttpSession based authentication, first a valid HttpSession has to be established via the login page in a browser. It is then possible to call any REST resources e.g. via Javascript.

Output Formats

The REST API supports the response in JSON.

Resources

The REST API allows you to manage articles.

REST API: Articles

URI: /rest/api/1/kb/{model-namespace}/articles

Http Method: GET /articles

Returns a list of KB articles based on the optional query parameters. Note: By default, the content of the articles is skipped due to performance and bandwith reasons.

Authentication

  • Knowledge Base Viewer
  • Knowledge Base Editor
  • Knowledge Base Manager
  • (if configured) Members (Support-Team, Incident Manager) of the linked Spider Incident model.

Query Parameters

NameDescriptionRequiredTypeExample Value
 queryString A query string to fulltext search for articles No String some%20value
 categoryUuid If set, the query will search only for articles linked with this category. No String a0bbf887-ce06-4835-8e79-d7a7d95b85f9
 includeCategorySubtree If set to true, subcategories of the selected category (categoryUuid) are included into the query  No boolean Default: true
 startAt The index of the first article to return (0-based). must be 0 or a multiple of maxResults  No int Default: 0
 maxResults The maximum number of articles to return. The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.  No int Default: 50
 expand If set to true, all returned articles are expanded and contain the same data as when fetching a single article  No boolean Default: false

Possible HTTP Status codes

  • 200: Request was successful
  • 401: User is not authenticated
  • 403: User does not have permission to view it.
  • 404: Articles not found, e.g. wrong wfm namespace

Response Data

Response data for the articles, see GET /article.

NameDescriptionType
 startAt The index of the first article  int
 maxResults The maximum number of articles to return.  int
 total The total number of found articles.  int
 highlight A text fragment that highlights the query hits on every article. The highlighted text is marked with html bold tags.  String
Example
curl -D- -u john:secret123 -X GET -H "Content-Type: application/json" http://example.com:8080/operationsmanager/rest/api/1/kb/mykb/articles&queryString=some%20Text

Response Body

{ "startAt": 0, "maxResults": 50, "total": 7, "article": [ { "id": "KB-00311", "uuid": "26fa5737-9217-4fb5-a9d6-17112da1069e", "subject": "HOW-TO: Silent installation for non WHQL-signed drivers", "creator": "John Doe", "lastEditor": "John Doe", "publishDate": "2014-04-08T07:37:34.841+0000", "updateDate": "2014-04-08T07:37:34.841+0000", "categories": [ { "uuid": "a0bbf887-ce06-4835-8e79-d7a7d95b85f9", "name": "Category Sub AA" } ], "highlight": ":In your <B>test</B> environment, install the program fully and be sure to click \n'Always", "visibility": "PUBLIC", "url": "http://example.com:8080/operationsmanager/faces/kb/mykb/article/KB-00311" }, { "id": "KB-00150", "uuid": "8fc571f9-65f7-4f92-a0eb-7dca2271cde6", "subject": "HOW TO: set security for new keys with REGPERM", "creator": "John Doe", "lastEditor": "Jim Knopf", "publishDate": "2014-04-08T07:37:22.961+0000", "updateDate": "2014-05-09T10:47:09.772+0000", "categories": [ { "uuid": "a0bbf887-ce06-4835-8e79-d7a7d95b85f9", "name": "Category Sub AA" } ], "highlight": " you \nspecified, for example: \n\n\nRegPerm 'HKEY_LOCAL_MACHINE' 'Software\\<B>test</B>", "visibility": "PUBLIC", "url": "http://example.com:8080/operationsmanager/faces/kb/mykb/article/KB-00150" }, ... ] }

REST API: Article

URI: /rest/api/1/kb/{model-namespace}/article

Http Method: POST /article

Create a new KB article based on the submitted data.

Authentication

  • Knowledge Base Editor
  • Knowledge Base Manager

Parameters

No parameters.

Possible HTTP Status codes

  • 201: Article was created successfully
  • 400: Input is invalid. e.g. missing required fields, invalid field values
  • 401: User is not authenticated
  • 403: User is not allowed to create a KB article

Request Data

NameDescriptionRequiredTypeExample Value
 subject The subject of the article Yes String Some Subject
 categories A list of existing category uuids Yes String 4308d03b-d879-4dc7-a9c9-c62cd868f92f
 content The article body. This can be HTML formatted Yes String This is a test.
 creator The name of the author. If empty, the authenticated user is set as creator.  No String John Doe
 visibility Defines if this article is public or private. Default is public  No String PUBLIC, PRIVATE

Response
The URI of the newly created article.

Example
curl -D- -u john:secret123 -X POST --data "@newarticle.json" -H "Content-Type: application/json" http://example.com:8080/operationsmanager/rest/api/1/kb/mykb/article

JSON data

{ "subject": "New KB Article from REST Client with category", "categories": [{ "uuid": "a0bbf887-ce06-4835-8e79-d7a7d95b85f9", "name": "Category A" }], "content": "This is another kb article." }
Http Method: GET /article/{articleId}

Returns a full representation of the KB article for the given article ID.

Authentication

  • Knowledge Base Viewer
  • Knowledge Base Editor
  • Knowledge Base Manager
  • (if configured) Members (Support-Team, Incident Manager) of the linked Spider Incident model.

Parameters

No parameters.

Possible HTTP Status codes

  • 200: Request was successful
  • 401: User is not authenticated
  • 403: User does not have permission to view it.
  • 404: Article was not found

Response Data

NameDescriptionTypeExample Value
 id The id of the article String KB-00012
 uuid The unique uuid of the article String 515bfd16-f765-4099-bbbc-e73bf0dae19c
 subject The subject of the article String Some Subject
 creator The name of the author.  String John Doe
 lastEditor The last editor of the article.  String Jim Knopf
 publishDate The date when this article was published.  ISO-8601 compliant notation 2013-03-21T11:18:34.000+0000
 updateDate The date when this article was updated the last time.  ISO-8601 compliant notation 2013-03-21T11:18:34.000+0000
 categories A list of categories where this article is linked to. List of categories (uuid and name) 
 content The article body. This can be HTML formatted String This is a test.
 visibility Defines if this article is public or private.  String PUBLIC, PRIVATE
 state Defines the state of this article.  String PUBLISHED, DRAFT
 url The URL to read this article in a web browser.  Stringhttp://example.com:8080/operationsmanager/faces/kb/mykb/article/KB-00012
Example
curl -D- -u john:secret123 -X GET -H "Content-Type: application/json" http://example.com:8080/operationsmanager/rest/api/1/kb/mykb/article/KB-00012

Response Body

{ "id": "KB-00012", "uuid": "515bfd16-f765-4099-bbbc-e73bf0dae19c", "subject": "Sample Article", "creator": "John Doe", "lastEditor": "Jim Knopf", "publishDate": "2013-03-21T11:18:34.000+0000", "updateDate": "2013-03-21T11:22:48.000+0000", "categories": [{ "uuid": "aa2bef41-34db-4aa2-91c9-2bf55ae76afa", "name": "Category A" }, { "uuid": "2ac1c80d-84d6-498f-b959-163040478542", "name": "Category B" }], "content": "This is a sample content", "visibility": "PRIVATE", "state": "PUBLISHED", "url": "http://example.com:8080/operationsmanager/faces/kb/mykb/article/KB-00012" }
Http Method: DELETE /article/{articleId}

Deletes a KB article based on the article ID.

Authentication

  • Knowledge Base Editor
  • Knowledge Base Manager

Parameters

No parameters.

Possible HTTP Status codes

  • 204: If the article was deleted successfully
  • 401: If the user is not authenticated
  • 403: If the user does not have permissions to delete this article
  • 404: If the article was not found
Example
curl -D- -u john:secret123 -X DELETE http://example.com:8080/operationsmanager/rest/api/1/kb/mykb/article/KB-00012

REST API: Categories

URI: /rest/api/1/kb/{model-namespace}/categories

Http Method: POST /categories

Returns a list of KB categories.

Authentication

  • Knowledge Base Viewer
  • Knowledge Base Editor
  • Knowledge Base Manager
  • (if configured) Members (Support-Team, Incident Manager) of the linked Spider Incident model.

Parameters

No parameters.

Possible HTTP Status codes

  • 200: Request was successful
  • 401: User is not authenticated
  • 403: User does not have permission to view it.
  • 404: Categories not found (e.g. wrong wfm namespace)
Example
curl -D- -u john:secret123 -X GET -H "Content-Type: application/json" http://example.com:8080/operationsmanager/rest/api/1/kb/mykb/categories

Response Body

[ { "name": "Category A", "uuid": "111ae470-7ca1-45f3-ac33-088f8ba629a0", "categories": [ { "name": "Category Sub AA", "uuid": "a0bbf887-ce06-4835-8e79-d7a7d95b85f9", "parentUuid": "111ae470-7ca1-45f3-ac33-088f8ba629a0" }, { "name": "Category Sub AB", "uuid": "1911506d-b45f-4cb2-8428-102fa3a23074", "parentUuid": "111ae470-7ca1-45f3-ac33-088f8ba629a0" } ] }, { "name": "Category B", "uuid": "cecf091c-f560-4119-82e8-9505b4d9c763" }, { "name": "Category C", "uuid": "18e4aee1-df11-42c4-b444-d787231e1b9d" } ]

.