Using API Examples from Docs

Introduction

API examples in Canonic provide a convenient way to understand how to interact with your workflows programmatically. For each workflow, Canonic generates sample cURL requests filled with fake data that corresponds to the input structure you've defined in your API node's settings.

Understanding API Examples

Each API example consists of:

• cURL request: This represents how an external system can call your Canonic API.
• Response: A sample response with fake data that the API will return when called successfully.

Sample cURL Request

A cURL request generated by Canonic might look like this:

curl 'https:/app.canonic.dev/app/sample-project/api/book' \
  --request POST \
  --header "Content-type: application/json" \
  --header "Authorization: [Access-Token]" \
  --data '{
    "input": {
      "title": "Uwsica de.",
      "image": {
        "url": "http://epbek.ua/pur.png",
        "name": "or.png"
      }
    }
  }'

Sample Response

The response from the API call will provide a structure indicating a successful interaction with your API:

{
  "success": true,
  "data": {
    "_id": "9d3825bc54ddd603c34ac883",
    "createdAt": "2031-01-21T07:36:15.820Z",
    "updatedAt": "2108-03-15T06:34:59.016Z",
    "title": "Hev wila.",
    "image": {
      "url": "http://leblawemi.to/zuabiji.png",
      "name": "uwuzapif.png"
    }
  }
}

Customizing API Requests

To tailor the API requests to your needs within Canonic's workflow:

• Modify the Payload: Adjust the --data payload in the API node settings to align with the structure your API expects.
• Input Configuration: Define the type of input your API will accept based on the desired operations within the API node's settings.

Authentication

For operations that modify data, secure authentication is required:

1. Access Token: Retrieve an Auth token from the 'Access Tokens' section found in the Project Settings.

2. cURL Request: Include the Auth token in your cURL request header as follows:

   Authorization: Bearer YOUR_ACCESS_TOKEN

   Note: While read operations may be performed without authentication, write and delete actions mandate a valid Access Token.

Example

To use the API examples with Postman:

1. Create a New Request: Open Postman and create a new request.
2. Set HTTP Method and URL: Set the HTTP method and URL to match the cURL example.
3. Add Headers: In the 'Headers' section, add any necessary headers from the cURL example, such as Content-type and Authorization.

4. Include Payload: If using a method that includes a payload (like POST, PUT, or PATCH), go to the 'Body' tab, select 'raw', and paste the JSON payload from the --data argument.

5. Send Request: Click 'Send' to execute the request and view the response in Postman.

Best Practices

When interacting with the Canonic API, adhere to the following best practices for a seamless experience:

• Testing: Utilize the API examples generated by Canonic to ensure your workflow operates correctly.
• Data Accuracy: Remember that the sample data provided in examples is solely for demonstration. Replace it with real data that is applicable to your specific scenarios when making actual API calls.

Ensure the correct endpoint paths and valid tokens are used in your cURL requests. This Markdown documentation is crafted to offer clear instructions on customizing API requests, managing authentication, and implementing best practices for using API examples within Canonic workflows.