Using AppDirect AI APIs

As APIs are built using REST principles, each API has a predictable resource-oriented URL, accepts form-encoded request bodies, returns responses in JSON format, and utilizes standard HTTP response codes, authentication mechanisms, and verbs.

Authentication

API authentication is the process of confirming the identity of a user making an API request, and it is a critical component of API security. The main goal of the authentication mechanism is to protect sensitive data and ensure that the APIs are not misused.

The AppDirect AI APIs use keys to authenticate requests. An API key is a unique identifier that is provided to registered users to control usage and monitor access.

The API key must be sent with every request as a request header.

Getting Started

This article provides instructions on how to get started with the AppDirect REST APIs using cURL.

Understanding elements of an API request

This section describes the elements that are required to make an API request:

• HTTP method

  The HTTP method of an endpoint defines the type of action performed on a given resource. Following are some of the commonly used methods:

  • GET - Used to retrieve resource details.
  • POST - Used for new resources.
  • PUT - Used to update an existing resource.
  • DELETE - Used to delete resources.
  • PATCH - Used to make a partial update on a resource.

  The reference documentation provides the HTTP method for every endpoint.

• Path

  Each API endpoint has a path. The reference documentation provides a path for every endpoint. For example, the path for the “Get AI Details” API is /api/v1/ai/{aiId}. The curly brackets {} in a path represent path parameters that you need to specify. In this example, replace aiId with the identifier of the AI whose details are to be retrieved.

• Headers

  Headers are a part of the HTTP requests and responses that include metadata in key-value pairs. They can be used for defining caching behavior, enabling authentication, and handling session state.

  HTTP headers significantly influence server and client behavior throughout the request and response cycle. Request headers (sent by the client) provide information and instructions about the requested resource, while response headers (sent by the server) provide metadata, instructions, and additional information about the response.

  Following are some of the most commonly used request headers:

  • Accept

    The Accept header specifies the media types the client can accept from the server, such as application/json or text/html, enabling the server to send the appropriate resource representation.

  • User-Agent

    The User-Agent header identifies the web browser or client application that is making the request, allowing the server to customize its response to the client.

  • X-Authorization

    The Authorization header sends client credentials to the server when accessing protected resources. For example, the client might include a JSON Web Token (JWT), which the server verifies before returning the requested resource.

  • Content-Type

    The Content-Type header indicates the media type of the content in the request body. For example, Content-Type:application/json indicates that the request body contains the JSON data which aids the server in interpreting and processing the payload.

  • Cookie

    The Cookie header allows clients to send stored cookies back to the server, enabling the server to associate requests with specific users or sessions for personalized experiences.

  Following are some of the most commonly used response headers:

  • Content-Type

    The Content-Type response header indicates the type of data that the server is sending to the client. It typically includes media type (such as text/html, application/json) and any optional parameters.

  • Cache-Control

    The Cache-Control header regulates caching behavior in the client’s browser or intermediate caches. It defines the response cache duration, expiration date, and revalidation.

  • Server

    The Server header contains details about the technology stack of the server that generated the response along with its name and version.

  • Set-Cookie

    The Set-Cookie header instructs clients to store a cookie with specific attributes, enabling stateful communication and personalized experiences in subsequent requests.

  • Content-Length

    The Content-Length header in the response body allows clients to anticipate data size. This improves performance as it allows clients to plan efficient memory allocation and data processing in advance.

• Authentication

  Every AppDirect REST API endpoint requires authentication. To authenticate your request, you must provide an authentication token with the necessary scopes or permissions.

• Parameters

  API methods often require or allow you to send additional information in parameters with your request. Following are some of the different types of parameters:

  • Path parameters

    Path parameters are sent along with a URL that points to a specific resource. They are separated from a URL using a backward slash (‘/’) and are required.

  • Body parameters

    Body parameters enable you to send additional data to an API, which can be optional or required depending on the endpoint.

  • Query parameters

    Query parameters enable you to manage what data is returned for a request. They are separated using a question mark (‘?’) and are usually optional.

Making a request

This section describes how to make an authenticated request to the AppDirect REST APIs using cURL:

1. Install cURL

   Install cURL before you proceed with the next steps. For more information, refer to cURL documentation.

2. Selecting an endpoint for your request

   • Select an endpoint you want to make a request to. You can refer to AppDirect AI API to discover the endpoints.

   • Identify the HTTP method and path of the endpoint. You will send these with your request.

     For example, the “Create a new chat session for the AI” endpoint uses the HTTP method POST and path /api/v1/ai/{aiId}/chats.

   • Identify the required parameters. For example, the “Create a new chat session for the AI" endpoint uses the path parameter {aiId} and body parameter name. Replace both parameters with the desired values.

3. Getting API key for authentication

   Create an access token to authenticate your request. You will need to send this token in an Authorization header with your request. To generate an API key, refer to API Keys.

4. Preparing a cURL request

   You should use the curl command to make your request. Include the following options and values in your request:

   • --request or -X followed by the HTTP method as the value.

   • --url followed by a full path as the value. The full URL must include the base URL for the AppDirect REST API (https://api.appdirect.com) and the path of the endpoint. For example, the url for the “Create a new chat session for the AI” will look like this:

     https://api.appdirect.com/api/v1/ai/{aiId}/chats.

   • --header or -H:

     • Accept: Pass the media type in an Accept header.
     • ** X-AppDirect-Api-Version:** Pass the API version in a X-AppDirect-Api-Version header.
     • X-Authorization: Pass your authentication token in an Authorization header.

   • --data or -d followed by any body parameters within a JSON object.

   Following is the example request for “Create a new chat session for the AI” endpoint:

   curl --request POST \
   --url “https://api.appdirect.com/api/v1/ai/12345/chats” \
   --header “Accept: application/json \
   --header “X-AppDirect-Api-Version: 1” \
   --header “X-Authorization: 123458acfgtkdasdiggd123hhhhd” \
   --data ‘{
   “name”: “Chat session 1”
   }

5. Understanding the response

   Every API request will return the response status code (standard HTTP response code), response headers, and potentially a response body.

   Following is the example response for “Create a new chat session for the AI” endpoint:

   {
      "id": "string",
      "createdAt": "2024-01-24T15:03:20.270Z",
      "updatedAt": "2024-01-24T15:03:20.270Z",
      "name": "string",
      "userId": "string",
      "pinPosition": 0,
      "ai": {
          "id": "string",
          "name": "string",
          "src": "string",
          "description": "string",
          "userId": "string",
          "userName": "string"
      }
   }