| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <!doctype html><html lang="en"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><meta name="description" content="An open source API to convert natural language into actions."><meta name="author" content="NLPCraft."><title>Apache NLPCraft - Natural Language Interface</title><link href="//netdna.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css" rel="stylesheet"><link href="//use.fontawesome.com/releases/v5.7.1/css/all.css" integrity="sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr" rel="stylesheet" crossorigin="anonymous"><link href="/ext/syntaxhighlighter/styles/shCoreNLPCraft.css" rel="stylesheet" type="text/css"><link href="/ext/syntaxhighlighter/styles/shThemeNLPCraft.css" rel="stylesheet" type="text/css"><link href="//fonts.googleapis.com/css?family=Amatic+SC|Roboto+Mono" rel="stylesheet"> <script src="/ext/syntaxhighlighter/scripts/XRegExp.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shCore.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushXml.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushPlain.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushJava.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushScala.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushPython.js" type="text/javascript"></script> <script src="/ext/syntaxhighlighter/scripts/shBrushJScript.js" type="text/javascript"></script> <script async defer src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" type="text/css" href="/assets/css/style.css"/> <script type="text/javascript" src="//use.typekit.net/pso2adz.js"></script> <script type="text/javascript"> try { Typekit.load(); } catch(e) { // Ignore. } </script><nav class="navbar navbar-expand-lg navbar-light bg-light" id="top-header"> <a class="navbar-brand mr-4" href="/index.html"> <img src="/images/nlpcraft_logo_white.gif" height="24px"> </a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button><div class="collapse navbar-collapse" id="navbarSupportedContent"><ul class="navbar-nav mr-auto"><li class="nav-item"> <a class="nav-link" href="/index.html#features">Features</a><li class="nav-item"> <a class="nav-link" href="/docs.html">Docs</a><li class="nav-item"> <a class="nav-link" href="/download.html">Downloads <i class="fas fa-download"></i></a><li class="nav-item"> <a class="nav-link" href="/community.html">Community</a><li class="nav-item"> <a class="nav-link" href="/use-cases.html">Use Cases</a></ul><ul class="navbar-nav ml-auto"><li class="nav-item mr-2"> <a class="nav-link" href="/download.html">v.0.5.0</a><li class="nav-item"> <a class="nav-link fork-link" target="github" href="https://github.com/apache/incubator-nlpcraft">GitHub <img height="20px" src="/images/github_logo_white.png"></a></ul></div></nav><div class="container-fluid"><div class="navbar-aligned"><ol class="breadcrumb"><li class="mr-1"><a href="/index.html">Home</a><li class="mr-1 active">REST API</ol><h1 class="page-title"> <span><i class="fas fa-fw fa-book"></i> REST API</span></h1><div class="three-cols-container"><div class="col-md-2 first-column"><ul class="side-nav"><li class="side-nav-title">Introduction<li> <a href="/docs.html">Overview</a><li> <a href="/installation.html">Installation</a><li> <a href="/getting-started.html">Getting Started</a><li class="side-nav-title">Developer Guide<li> <a href="/basic-concepts.html">Basic Concepts</a><li> <a href="/first-example.html">First Example</a><li> <a href="/data-model.html">Data Model</a><li> <a href="/intent-matching.html">Intent Matching</a><li> <a class="active" href="/using-rest.html">REST API</a><li> <a href="/server-and-probe.html">Server <span class="amp">&</span> Probe</a><li> <a href="/metrics-and-tracing.html">Metrics <span class="amp">&</span> Tracing</a><li> <a href="/integrations.html">Integrations</a><li class="side-nav-title">Examples<li> <a href="/examples/alarm_clock.html">Alarm Clock</a><li> <a href="/examples/light_switch.html">Light Switch</a></ul></div><div class="col-md-8 second-column"><section id="overview"><h2 class="section-title">Overview</h2><p> REST API provides a universal integration path for any type of user application to connect to and use NLPCraft. By using REST API these applications can ask natural language questions, get results and perform many supporting operations such as user management.</p><p> REST server accepts the REST call, interprets and routes it to the appropriate data probe which in turn invokes one of its deployed data models. The result of data model processing travels all the way through the same chain of components back to the user application that made the original call.</p><p> In this chapter we'll provide an overview on using REST API. Note that the full REST API specification is hosted on <a href="https://nlpcraft.docs.apiary.io" target="apiary">apiary.io</a> where you can review it and test with it against your localhost or remote NLPCraft installation.</p><div class="bq warn"><p> <b>apiary.io <span class="amp">&</span> localhost</b></p><p> If you are using <a href="https://nlpcraft.docs.apiary.io" target="apiary">apiary.io</a> to test REST API against localhost make sure to install Chrome Apiary extension. Note that this will only work in Chrome browser.</p></div><div class="bq info"><p> If you downloaded ZIP archive the REST API specification is also available in <code>openapi/nlpcraft_swagger.yml</code> file or on <a target="github" href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml">GitHub</a>.</p></div></section><section id="java-client"><h3 class="section-title">Java Client <i class="fab fa-java"></i></h3><p> NLPCraft provide native Java client that enables easy-to-use Java-based API wrapping standard NLPCraft REST APIs. It can be used by any JVM language that provides Java interop such as Scala, Groovy, or Kotlin:</p><ul><li>Maven/Grape/Gradle/SBT <a href="download.html#java-client">instructions</a><li>Latest <a target=_ href="https://apache.github.io/incubator-nlpcraft-java-client/apis/latest/index.html">Javadoc</a><li>Watch, star or fork <a target="github" href="https://github.com/apache/incubator-nlpcraft-java-client">GitHub Project</a></ul></section><section id="format"><h3 class="section-title">REST URL</h3><p> REST API accepts only <code>POST</code> HTTP calls and <code>application/json</code> content type for JSON payload and responses. When issuing a REST call you will be using the following URL:</p><pre class="brush: plain"> |
| https://localhost:8081/api/v1/signin |
| </pre><p> where:<dl><dt><code>http</code><dd>Either <code>http</code> or <code>https</code> protocol.<dt><code>localhost:8081</code><dd>Host and port on which REST server is started. <code>localhost:8081</code> is the default configuration and can be <a href="server-and-probe.html">changed</a>.<dt><code>/api/v1</code><dd>Mandatory prefix indicating API version.<dt><code>/signin</code><dd>Specific REST call.</dl><div class="bq info"><p> <b>bin/nccurl.sh</b></p><p> <a target="wiki" href="https://en.wikipedia.org/wiki/CURL">cURL</a> is an excellent utility for testing REST services from the command line and scripts. NLPCraft comes with a convenient wrapper script <code>bin/nccurl.sh</code> that shortens command line of the standard cURL. We recommend adding <code>bin/nccurl.sh</code> to your <code>$PATH</code> environment variable.</p></div><p> REST API is divided into five functional groups:</p><ul><li><a href="#auth">Authentication</a><li><a href="#asking">Asking</a><li><a href="#company">Company Management</a><li><a href="#user">User Management</a><li><a href="#data_probe">Data Probe Management</a></ul><div class="bq info"> <b>Admins</b><p> Note that many operations are only available to the users with administrative privileges. Note also that some operations will implicitly behave differently based on whether the currently signed in user have administrative privileges or not.</p></div><div class="bq info"> <b>External User ID</b><p> Many calls on REST API accept external "on-behalf-of" user ID (<code>usrExtId</code>) additionally to the regular user ID (<code>usrID</code>). In these methods zero, one or both IDs must be provided. If none are provided the ID of the currently signed in user will be used. If both are provided they should point to the same user. External user ID allows to use user identification from the external systems without a need to import all the existing users into NLPCraft in the first place.</p><p> Typical usage pattern for integrating NLPCraft into existing system is to create a single administrative NLPCraft user, sign in with that account and then use external "on-behalf-of" user IDs in all the requests. This way you get the same functionality as if using ordinary user IDs but without a need to migrate and synchronize all user accounts from the existing system to NLPCraft.</p></div></section><section id="auth"><h3 class="section-title">Authentication</h3><p> Before performing any REST calls a registered user needs to sign in to receive an <b>access token</b> that will be used in all subsequent operations:</p><table class="gradient-table"><thead><tr><th>REST call<th>Description<tbody><tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/authentication"><nobr><code>/signin</code></nobr></a><td>Sign in and obtain <b>access token</b>.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/authentication"><nobr><code>/signout</code></nobr></a><td>Sign out and invalidate previously obtained <b>access token</b>.</table><div class="bq info"> <b>Default User</b><p> NLPCraft comes with a default built-in credentials that you can use when signing in for the first time:</p><ul><li>Email: <code>admin@admin.com</code><li>Password: <code>admin</code></ul></div><div class="bq warn"><p> In production environment make sure to delete this default user once you add at least one of your own users with administrative privileges.</p></div></section><section id="asking"><h3 class="section-title">Asking</h3><p> This is the main group of operation that allows to ask questions, check the status and get result:</p><table class="gradient-table"><thead><tr><th>REST call<th>Description<tbody><tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/ask</code></nobr></a><td>Submit the sentence to be processed <b>asynchronously</b>.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/ask/sync</code></nobr></a><td>Submit the sentence to be processed <b>synchronously</b>.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/check</code></nobr></a><td>Get statuses and results for previously submitted <code>/ask</code> requests.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/cancel</code></nobr></a><td> Remove results from the server memory.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/clear/conversation</code></nobr></a><td> Clear the conversation STM for current user and data model.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><nobr><code>/clear/dialog</code></nobr></a><td> Clear the dialog flow for current user and data model.</table></section><section id="company"><h3 class="section-title">Company Management</h3><p> This group of operations allows to add, update and remove companies in the systems.</p><table class="gradient-table"><thead><tr><th>REST call<th>Description<tbody><tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/company/get</code></nobr></a><td>Gets current user company.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/company/add</code></nobr></a><td>Add new company.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/company/update</code></nobr></a><td>Update company information.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/company/delete</code></nobr></a><td>Delete company.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/company/token/reset</code></nobr></a><td>Reset company's authentication token.</table></section><section id="user"><h3 class="section-title">User Management</h3><p> This group of operations allows to add, update and remove users in the systems:</p><table class="gradient-table"><thead><tr><th>REST call<th>Description<tbody><tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/get</code></nobr></a><td>Get current user information.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/all</code></nobr></a><td>Get all users.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/add</code></nobr></a><td>Add new user.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/update</code></nobr></a><td>Update user information.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/delete</code></nobr></a><td>Delete user.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/admin</code></nobr></a><td>Change user administrative privileges.<tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/users"><nobr><code>/user/passwd/reset</code></nobr></a><td> Reset the current user password.</table></section><section id="data_probe"><h3 class="section-title">Data Probe Management</h3><p> This group of operations allows to get the information about connected data probes:</p><table class="gradient-table"><thead><tr><th>REST call<th>Description<tbody><tr><td><a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/data-probes"><nobr><code>/probes/all</code></nobr></a><td>Get information about connected probes.</table></section><section id="server_errors"><h2 class="section-title">Server Errors</h2><p> When REST server returns HTTP error the response body contains JSON object (<code>Content-Type → application/json</code>) with two fields <code>code</code> and <code>msg</code>:</p><pre class="brush: js"> |
| { |
| "code": "NC_INVALID_ACCESS_TOKEN", |
| "msg": "Unknown access token: PPdxjwXBOIMpAWNgpKq1" |
| } |
| </pre><p> Following tables shows all possible <code>code</code> values for these server errors:</p><table class="gradient-table"><thead><tr><th>Code<th>Description<tbody><tr><td><code>NC_INVALID_ACCESS_TOKEN</code><td> The access token is invalid or no longer valid. Note that previously issued existing access tokens can expire or be otherwise invalidated and have to be obtained again.<tr><td><code>NC_SIGNIN_FAILURE</code><td> Invalid or unknown user email and/or user password during <code>/signin</code> call. This can indicate either the attempt to signin by the user that hasn't been added yet, or the invalid password for the existing user.<tr><td><code>NC_NOT_IMPLEMENTED</code><td> Particular feature is not implemented yet or not available. This is reserved for API extensions and future backward compatibility.<tr><td><code>NC_INVALID_FIELD</code><td> This indicated a problem with a field. It's either too bit, too small, empty or otherwise invalid. See <code>msg</code> field in the error response for details.<tr><td><code>NC_ADMIN_REQUIRED</code><td> Calling user is required to have admin privileges to execute given call.<tr><td><code>NC_INVALID_OPERATION</code><td> Indicates that a given operation cannot be performed as specified. For example, this error is returned when you attempt to remove or revoke admin privileges from the last admin user.<tr><td><code>NC_ERROR</code><td>Indicates a general server error.</table></section></div><div class="col-md-2 third-column"><ul class="side-nav"><li class="side-nav-title">On This Page<li><a href="#format">REST URL</a><li><a href="#auth">Authentication</a><li><a href="#company">Company</a><li><a href="#user">Users</a><li><a href="#asking">Asking</a><li><a href="#data_probe">Data Probes</a><li><a href="#server_errors">Server Errors</a><li class="side-nav-title">Quick Links<li> <i class="fab fa-fw fa-github mr-2"></i><a target="github" href="https://github.com/apache/incubator-nlpcraft/tree/master/src/main/scala/org/apache/nlpcraft/examples">Examples</a><li> <i class="fab fa-fw fa-java mr-2"></i><a target="_" href="/apis/latest/index.html">Javadoc</a><li> <i class="fas fa-fw fa-code mr-2"></i><a href="https://github.com/apache/incubator-nlpcraft/blob/master/openapi/nlpcraft_swagger.yml" target="github">REST API</a><li> <i class="fas fa-fw fa-download mr-2"></i><a href="/download.html">Download</a><li class="side-nav-title">Support<li> <nobr> <i class="fab fa-fw fa-jira mr-2"></i><a target="jira" href="https://issues.apache.org/jira/projects/NLPCRAFT/issues">JIRA</a> </nobr><li> <nobr> <i class="far fa-fw fa-envelope mr-2"></i><a href="http://mail-archives.apache.org/mod_mbox/nlpcraft-dev/">Dev List</a> </nobr><li> <nobr> <i class="fab fa-fw fa-stack-overflow mr-2"></i><a target="so" href="https://stackoverflow.com/questions/ask">Stack Overflow</a> </nobr><li> <nobr> <i class="fab fa-fw fa-github mr-2"></i><a target="github" href="https://github.com/apache/incubator-nlpcraft">GitHub</a> </nobr></ul></div></div></div></div><div id="footer"><div class="container"><div class="text-muted text-center"> <span>Copyright © 2020 Apache Software Foundation</span> <span> <a target=_new href="https://apache.org"><img alt="asf" src="/images/asf_logo.png" height="24px"></a> </span> <a target="asf" href="http://apache.org/foundation/policies/privacy.html" class="btn btn-link ml-4">Privacy</a> <span class="sep">•</span> <a href="/index.html#news" class="btn btn-link">News</a> <span class="sep">•</span> <a href="/docs.html" class="btn btn-link">Docs</a> <span class="ml-4">release: <a href="/download.html"><code>0.5.0</code></a></span> <span class="ml-2"> <a target="jenkins" href="https://builds.apache.org/view/Incubator%20Projects/job/incubator-nlpcraft/"><img src="https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fbuilds.apache.org%2Fview%2FIncubator%2520Projects%2Fjob%2Fincubator-nlpcraft%2F"></a> <a target=_ href="https://gitter.im/apache-nlpcraft/community"><img alt="Gitter" src="https://badges.gitter.im/apache-nlpcraft/community.svg"></a> </span></div></div></div><script src="//code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.0/umd/popper.min.js" integrity="sha384-cs/chFZiN24E4KMATLdqdvsezGxaGsi4hLGOzlXwp5UZB1LY//20VyM2taTB4QvJ" crossorigin="anonymous"></script> <script src="//stackpath.bootstrapcdn.com/bootstrap/4.1.0/js/bootstrap.min.js" integrity="sha384-uefMccjFJAIv6A+rW+L4AHf99KvxDjWSu1z9VI8SKNVmz4sk7buKt/6v9KI65qnm" crossorigin="anonymous"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.4/lodash.min.js" type="text/javascript" ></script> <script src="//cdnjs.cloudflare.com/ajax/libs/moment.js/2.12.0/moment.min.js" type="text/javascript" ></script> <script src="//cdnjs.cloudflare.com/ajax/libs/moment-timezone/0.5.5/moment-timezone-with-data.min.js" type="text/javascript" ></script> <script type="text/javascript"> SyntaxHighlighter.defaults["auto-links"] = false; SyntaxHighlighter.defaults["tab-size"] = 2; SyntaxHighlighter.all(); </script> |
