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 and XML 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 two formats: JSON and XML.

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

Name Description Required Type Example 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.

Name Description Type
 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

Name Description Required Type Example 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

Name Description Type Example Value  Notes
 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  
 creationDate  The date when this article was created.  ISO-8601 compliant notation  2013-03-21T11:18:34.000+0000  since 4.5.20
 published  If this article was published or not  boolean  true  since 4.5.20
 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.  
 tags A list of optional tags for this article  List of tags (tag-name)    since 4.5.20
 visibility  Defines if this article is public or private.   String  PUBLIC, PRIVATE  
 state  Defines the state of this article.   String  PUBLISHED, DRAFT  
 featured  If this article is featured or not  boolean  false  since 4.5.20
 views No. of article views (web only)  Integer 1234  since 4.5.20
 rating The average article rating (0 - 100)  Integer  80  since 4.5.20
 voters  The number of  rating voters for this article  Integer  2  since 4.5.20
 url  The URL to read this article in a web browser.   String http://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", "creationDate": "2013-03-21T11:18:34.000+0000", "published": true, "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" }], "tags": [{ "tag": "Some Tag" }], "content": "This is a sample content", "visibility": "PRIVATE", "state": "PUBLISHED", "featured": false, "views": 1234, "rating": 80, "voters": 2, "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" } ]