• Features
  • Docs & Tutorials
  • Downloads
  • Blog
  • Community
  • Use Cases
  • v.0.7.4
  • GitHub
  1. Home
  2. REST API

REST API

  • Introduction
  • Overview
  • Installation
  • Getting Started
  • Developer Guide
  • Basic Concepts
  • First Example
  • Data Model
  • Intent Matching
  • REST API
  • Server & Probe
  • Metrics & Tracing
  • Integrations
  • Tools
  • nlpcraft.{sh|cmd}
  • Test Framework
  • Embedded Probe
  • SQL Model Generator
  • Synonyms Tool
  • Examples
  • Alarm Clock
  • Light Switch
  • Weather Bot
  • SQL Model

TL;DR;

View Open API Specification in a separate window. 👌

...bit more details

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.

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.

If you downloaded ZIP archive the REST API specification is also available in openapi/nlpcraft_swagger.yml file or on GitHub.

Java Client

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:

  • Maven/Grape/Gradle/SBT instructions
  • Latest Javadoc
  • Watch, star or fork GitHub Project

REST URL

REST API accepts only POST HTTP calls and application/json content type for JSON payload and responses. When issuing a REST call you will be using the following URL:

            https://localhost:8081/api/v1/signin
        

where:

http
Either http or https protocol.
localhost:8081
Host and port on which REST server is started. localhost:8081 is the default configuration and can be changed.
/api/v1
Mandatory prefix indicating API version.
/signin
Specific REST path.

Management Script

bin/nlpcraft.{sh|cmd} script is a central management utility for NLPCraft. Among many commands it provides, there are two commands call and rest that allows for simple and effective REST API usage against local REST server.

Users & Organizations

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.

Default Account

NLPCraft comes with the default account:

  • Email: admin@admin.com
  • Password: admin

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.

âš  Default Account âš 

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.

Admins

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.

External User ID

Many calls on REST API accept external "on-behalf-of" user ID (usrExtId) additionally to the regular user ID (usrID). 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.

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.

Server Errors

When REST server returns HTTP error the response body contains JSON object (Content-Type → application/json) with two fields code and msg:

        {
            "code": "NC_INVALID_ACCESS_TOKEN",
            "msg": "Unknown access token: PPdxjwXBOIMpAWNgpKq1"
        }
        

Following tables shows all possible code values for these server errors:

CodeDescription
NC_INVALID_ACCESS_TOKEN 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.
NC_SIGNIN_FAILURE Invalid or unknown user email and/or user password during /signin 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.
NC_NOT_IMPLEMENTED Particular feature is not implemented yet or not available. This is reserved for API extensions and future backward compatibility.
NC_INVALID_FIELD This indicated a problem with a field. It's either too bit, too small, empty or otherwise invalid. See msg field in the error response for details.
NC_ADMIN_REQUIRED Calling user is required to have admin privileges to execute given call.
NC_INVALID_OPERATION 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.
NC_ERRORIndicates a general server error.
  • On This Page
  • Java Client
  • REST URL
  • Users & Org
  • Server Errors
  • Quick Links
  • Examples
  • Javadoc
  • REST API
  • Download
  • Cheat Sheet
  • Support
  • JIRA
  • Dev List
  • Stack Overflow
  • GitHub
  • Gitter
Copyright © 2021 Apache Software Foundation asf Events • Privacy • News • Docs release: 0.7.4 Gitter Built in: