Skip to main content

How to create an API Command

Guide to creating a custom API Command in Encompass: define its purpose, set up API tokens and permission codes, build and test the logic, and fix errors like 401 Unauthorized. Requires v25.01+.

B
Written by Bailey Naas-Thornton

Minimum Version Required: 25.01

Pre-Conditions

  • You have access to the API management interface of your system.
    ​
    ​

  • You have the necessary permissions to create new API commands.
    ​
    ​

  • You understand the purpose and functionality of the API command you intend to create.
    ​
    ​

  • You have a clear understanding of the data source (if applicable) and the desired outcome of the API command.
    ​
    ​

  • You may need specific API tokens or credentials depending on the API command's function.
    ​
    ​

  • It is recommended to have a test environment to build and test your API command before deploying it to your live environment.

Steps

  1. Define the API Command's Purpose:
    ​
    ​

    • Clearly define what this new API command should accomplish. What data should it retrieve, process, or modify? What will be the input and output?
      ​
      ​

    • Example: Generating a document from data, importing data into a table.
      ​
      ​
      ​

  2. Identify Necessary Resources and Functionality:
    ​
    ​

    • Determine what components or features your API command will need to interact with. This might include:
      ​
      ​

      • Specific data sources (e.g., other APIs, databases, documents).
        ​
        ​

      • Existing API functionalities that can be leveraged.
        ​
        ​

      • Custom code or logic (e.g., cloud functions).
        ​
        ​

      • Specific permissions required to access data or perform actions.
        ​
        ​

    • Example: Needing to inherit TableImport functionality for importing data.
      ​
      ​
      ​

  3. Create the API Command:
    ​
    ​

    • Use the API management interface to create a new API command.
      ​
      ​

    • Provide a clear and descriptive name and any necessary identifiers for your API command (e.g., API Command ID).
      ​
      ​

    • Configure the API command based on its intended purpose. This may involve:
      ​
      ​

      • Defining parameters that the API command will accept as input.
        ​
        ​

      • Specifying the logic or code that will be executed when the API command is called.
        ​
        ​

      • Setting up connections to data sources or other APIs.
        ​
        ​
        ​

  4. Configure Authentication and Authorization:
    ​
    ​

    • Determine how the API command will be authenticated and authorized. This often involves using API tokens.
      ​
      ​

    • API Tokens:
      ​
      ​

      • If your API command needs to access protected resources or perform specific actions, you will likely need an API token with the appropriate permissions.
        ​
        ​

      • Create a new API token or use an existing one.
        ​
        ​

      • Permissions: Ensure the API token has all the necessary permissions required for the API command to function correctly. This might include permissions to view, create, edit, or delete specific data or resources. You may need to consult documentation or support to identify the required permission codes. You can also (optionally) set the 'Required Permission' value on the API Command record itself. This will cause the system to always validate that the user or token calling the API has that specific permission.
        ​
        ​

      • Example: Needing "DocumentView", "EDI view", and potentially "ReportView" permissions. The Permission Code Arr field in the API Token settings is where these can be added, separated by '!'.
        ​
        ​
        ​

  5. Implement the API Command's Logic:
    ​
    ​

    • Implement the core functionality of your API command. This may involve writing code (e.g., in a cloud function) to:
      ​
      ​

      • Retrieve data from specified sources.
        ​
        ​

      • Process or transform data as needed.
        ​
        ​

      • Interact with other APIs or system components.
        ​
        ​

      • Format the output of the API command.
        ​
        ​
        ​

  6. Testing the API Command:
    ​
    ​

    • Thoroughly test the new API command in a test environment.
      ​
      ​

    • Send various requests with different parameters to ensure it functions as expected under different conditions.
      ​
      ​

    • Verify that the output is correct and that any intended actions are performed successfully.
      ​
      ​

    • Check for any errors or unexpected behavior.
      ​
      ​

    • Example: Encountering a 401 Unauthorized error or an empty response during testing.
      ​
      ​
      ​

  7. Deployment (Optional):
    ​
    ​

    • Once you have thoroughly tested the API command and are confident in its functionality, you can deploy it to your production environment if necessary. Follow your system's deployment procedures.
      ​
      ​
      ​

  8. Documentation:
    ​
    ​

    • Document the purpose, functionality, input parameters, output format, and any specific requirements or considerations for your new API command. This will be helpful for yourself and other users who may need to interact with it.
      ​
      ​
      ​

If you encounter issues:
​

  • Review Error Messages: Carefully examine any error messages you receive for clues about the problem.
    ​
    ​

  • Check API Token Permissions: Ensure the API token you are using has all the necessary permissions. Insufficient permissions are a common cause of errors (e.g., 401 Unauthorized, permission denied).
    ​
    ​

  • Verify API Command Logic: Double-check the code or configuration of your API command for any errors or incorrect settings.
    ​
    ​

  • Consult Documentation: Refer to your system's API documentation for information on specific methods, data types, and required permissions.
    ​
    ​

  • Contact Support: If you are unable to resolve the issue, reach out to your system's support team for assistance.
    ​
    ​

  • Provide the following information to support:
    ​
    ​

    • API Command ID of the new API command.
      ​
      ​

    • Detailed description of the issue and the steps you took to reproduce it.
      ​
      ​

    • Any error messages you are receiving.
      ​
      ​

    • Information about the API token you are using and its permissions.
      ​
      ​

    • Any relevant code snippets or configurations.

Fields And Definitions

  • API Command: A defined set of instructions that enables interaction between software systems.
    ​
    ​

  • API Token: A security key that verifies the identity of an application or user making an API request and grants access based on associated permissions.
    ​
    ​

  • Authentication: The process of verifying the identity of the user or application accessing the API.
    ​
    ​

  • Authorization: The process of determining what actions or resources the authenticated user or application is allowed to access.
    ​
    ​

  • Parameter: An input value that can be passed to an API command to customize its behavior.
    ​
    ​

  • Cloud Function: A serverless piece of code that can be executed in response to an event or an API call.
    ​

Best Practices

  • Start Simple: Begin with a basic version of your API command and add complexity incrementally, testing at each stage.
    ​
    ​

  • Follow Naming Conventions: Use clear and consistent naming conventions for your API commands and parameters.
    ​
    ​

  • Implement Error Handling: Include error handling in your API command logic to manage potential issues gracefully.
    ​
    ​

  • Secure Your API: Follow security best practices for API development, including proper authentication and authorization.
    ​
    ​

  • Monitor Your API: Once deployed, monitor the performance and usage of your API command.

Did this answer your question?