| --- |
| active_crumb: REST API |
| layout: documentation |
| id: rest |
| --- |
| |
| <!-- |
| 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. |
| --> |
| |
| <!--suppress HtmlDeprecatedTag --> |
| <div class="col-md-8 second-column"> |
| <section> |
| <h2 class="section-title">TL;DR; <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <p> |
| View <a target="swaggerhub" href="https://app.swaggerhub.com/apis-docs/Apache-NLPCraft/apache-nlpcraft/{{site.latest_version}}">Open API Specification</a> in a separate window. 👌 |
| </p> |
| </section> |
| <section id="overview"> |
| <h2 class="section-title">...bit more details <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></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> |
| <div class="bq info"> |
| <p> |
| If you downloaded ZIP archive the <a target="swaggerhub" href="https://app.swaggerhub.com/apis-docs/Apache-NLPCraft/apache-nlpcraft/{{site.latest_version}}">REST API specification</a> 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"> |
| <h2 class="section-title">Java Client <i class="fab fa-java"></i> <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <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> |
| <li>Latest <a target=_ href="/apis/java-client/latest/index.html">Javadoc</a></li> |
| <li>Watch, star or fork <a target="github" href="https://github.com/apache/incubator-nlpcraft-java-client">GitHub Project</a></li> |
| </ul> |
| |
| </section> |
| <section id="format"> |
| <h2 class="section-title">REST URL <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <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></dt> |
| <dd>Either <code>http</code> or <code>https</code> protocol.</dd> |
| <dt><code>localhost:8081</code></dt> |
| <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>.</dd> |
| <dt><code>/api/v1</code></dt> |
| <dd>Mandatory prefix indicating API version.</dd> |
| <dt><code>/signin</code></dt> |
| <dd>Specific REST path.</dd> |
| </dl> |
| <div class="bq info"> |
| <p> |
| <b>Management Script</b> |
| </p> |
| <p> |
| <a href="/tools/script.html"><code>bin/nlpcraft.{sh|cmd}</code></a> script is a <b>central management utility</b> for NLPCraft. Among many |
| commands it provides, there are two commands <code>call</code> and <code>rest</code> that allows for simple and |
| effective REST API usage against local REST server. |
| </p> |
| </div> |
| </section> |
| <section id="users"> |
| <h2 class="section-title">Users <span class="amp">&</span> Organizations <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <p> |
| In NLPCraft most of the REST calls require ID of the user. Every user belongs to a company, and each user |
| has administrative privileges flag. The notion of the user and company IDs additionally to the model ID provide |
| necessary attributes for proper probe authentication, conversation maintenance, and security. |
| </p> |
| <h2 class="section-sub-title">Default Account <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <p> |
| NLPCraft comes with the default account: |
| </p> |
| <ul> |
| <li><b>Email: </b>admin@admin.com</li> |
| <li><b>Password: </b>admin</li> |
| </ul> |
| <p> |
| This account has administrative privileges and should be used as a bootstrap account to create other accounts. |
| Make sure to delete this account when you go to production. |
| </p> |
| <div class="bq warn"> |
| <p><b><span style="font-size: 120%; color: #E67E22">âš </span> Default Account <span style="font-size: 120%; color: #E67E22">âš </span></b></p> |
| <p> |
| Make sure to delete the default account when you go to production or as soon as you have other secure |
| administrative account that can act as a bootstrap account. |
| </p> |
| </div> |
| <h2 class="section-sub-title">Admins <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <p> |
| 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> |
| <h2 class="section-sub-title">External User ID <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2> |
| <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> |
| </section> |
| <section id="server_errors"> |
| <h2 class="section-title">Server Errors <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></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> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code>NC_INVALID_ACCESS_TOKEN</code></td> |
| <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. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_SIGNIN_FAILURE</code></td> |
| <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. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_NOT_IMPLEMENTED</code></td> |
| <td> |
| Particular feature is not implemented yet or not available. This is reserved for API extensions and |
| future backward compatibility. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_INVALID_FIELD</code></td> |
| <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. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_ADMIN_REQUIRED</code></td> |
| <td> |
| Calling user is required to have admin privileges to execute given call. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_INVALID_OPERATION</code></td> |
| <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. |
| </td> |
| </tr> |
| <tr> |
| <td><code>NC_ERROR</code></td> |
| <td>Indicates a general server error.</td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| </div> |
| <div class="col-md-2 third-column"> |
| <ul class="side-nav"> |
| <li class="side-nav-title">On This Page</li> |
| <li><a href="#java-client">Java Client</a></li> |
| <li><a href="#format">REST URL</a></li> |
| <li><a href="#users">Users <span class="amp">&</span> Org</a></li> |
| <li><a href="#server_errors">Server Errors</a></li> |
| {% include quick-links.html %} |
| </ul> |
| </div> |
| |
| |
| |
| |
