Using iKnow
REST Interface
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

A REST API interface is provided for common iKnow tasks in the %iKnow.REST.v1 class. This REST API covers basics (querying domains & configurations), classic queries (including semantics), simple domain operations (adding/deleting sources, blacklist management) and support for the matching and dictionary APIs.

Here are some of the main characteristics of the API:
Swagger
The iKnow REST API is fully documented using the OpenAPI Specification (also known as Swagger). The description in YAML is available from the "/swagger" endpoint and can be loaded directly into swagger-ui for convenient GUI capabilities on top of this API.
To use it, either install swagger-ui or go to http://petstore.swagger.io and point to this endpoint.
Returning iKnow Data Using Swagger
The Swagger–UI display for each REST statement can be used to invoke the REST API directly, or to provide a Request URL value that can be used to invoke the REST API in a browser window (for GET requests).
To invoke a REST API directly, specify the required Parameters. Commonly, an iKnow REST API requires the domain ID parameter, specified as an integer number. For example, to GET the domain details of the domain with the ID of 2 generates the following Request URL:
http://localhost:57775/api/iknow/v1/user/domain/2/details
Note that the Swagger interface infers the namespace to use from the URL you used to access the /swagger endpoint. For example, to invoke the REST API in namespace SAMPLES, load the swagger endpoint using the URL:
http://localhost:57775/api/iknow/v1/samples/swagger
The iKnow data is returned to the browser in JSON format. For example, this Request URL returns the following JSON string for a domain named “crashes”:
{"id":"2","name":"crashes","parameters":{"DefaultConfig":"crashes.Configuration","DefinitionClass":"User.crashes","ManagedBy":"User.crashes"},"metadata":[{"id":1,"name":"DateIndexed","operators":["=","!=","<","<=",">",">="],"dataType":"date","storage":"normal","caseSensitive":0,"hidden":0}]}
REST Operations
The iKnow REST operations are grouped into the following topics:
While the core REST API supports access to any defined domain (by specifying the domain id at the start of almost every URL), you can also generate a domain-specific REST API, allowing you to expose a single domain through your webapp. To do this, use the CreateDomainAPI() method found in the %iKnow.REST.Base class, and then create a new web application referring to the newly created class as the “Dispatch Class”. This may be useful if you only want to enable access to a specific domain and have disabled the general /api/iknow/… web application.
For any of these REST operations, if the specified domain does not exist, the operation returns {"errors":[{"error":"ERROR #8021: Domain with id 7 does not exist","code":8021,"domain":"%ObjectErrors","id":"IKNoDomainWithId","params":["7"]}],"summary":"ERROR #8021: Domain with id 7 does not exist"}, unless stated otherwise.
Domains and Configurations
The iKnow REST operations for Domains and Configurations (categorized as “miscellaneous”) are the following:
Sources
The iKnow REST operations for sources are the following:
Entities
The iKnow REST operations for entities are the following:
Sentences
The iKnow REST operations for sentences are the following:
Paths and CRCs
The iKnow REST operations for Paths and CRCs (concept-relation-concept strings) are the following:
Dictionaries and Matching
The iKnow REST operations for dictionaries are the following:
The iKnow REST operations for matching operations using a dictionary are the following:
Blacklists
The iKnow REST operations for blacklists are the following: