Skip to main content

Getting Started

note

You can only generate the code sample API artifacts if this specific feature is enabled in your subscription. In case of any subscription issues, the API responds with appropriate error codes and messages. In case you run into such issues, please contact your account manager at APIMatic or send us an email at support@apimatic.io

Enabling Code Sample API Artifacts Generation for Docs as Code workflow​

The code sample API artifacts generation can be enabled by adding the codeSampleApi property at the root object of the build file as shown below.

"codeSampleApi": {
    "isEnabled": true,
    "defaultVersion": "1.0"
}

Key Properties​

  • isEnabled: (Boolean, required) Enables the generation of Code Sample API artifacts.
  • defaultVersion: (String, optional) This value should only be provided in case of multi-versioned portal. It defines the default version of the API to use when the version query parameter is not provided in the code sample API requests.

Output Structure​

When enabled, the generated artifacts are saved in a folder named code-sample-api at the root of the output directory. A typical folder structure is as follows:

index.html
code-sample-api/
├── data/
│ └── default.json
└── package.json
static/
├── css/
├── docs/
├── exports/
├── images/
├── js/
└── sdks/

The code-sample-api folder includes a package.json file, which defines the start script and lists the Code Sample API npm package as a dependency. Additionally, it contains a data folder with one or more JSON files that provide the API-specific data required by the Code Sample API.

Running the Code Sample API Locally​

The Code Sample API is distributed as an npm package that can be run locally. Follow the steps below to start a local server:

  1. Open a terminal and navigate to the code-sample-api directory in the docs-as-code output.

  2. Install dependencies using npm:

    npm install

  3. Start the API server:

    npm start

    The server will start locally on port 8080. You can access it using http://localhost:8080.

The Code Sample API provides a single POST endpoint available at /code/request. Below is an example of a cURL request and its corresponding JSON response.

Sample Request​

curl -X POST \
  --url 'http://localhost:8080/code/request?languages=typescript%2Cgo'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payload": {
    "args": {
      "id": "1001"
    }
  },
  "endpointName": "get-an-artist",
  "groupName": "Artists",
  "environment": "production",
  "auth": {
    "oauth_2_0": {
      "OAuthRedirectUri": "https://host.com",
      "OAuthClientId": "client",
      "OAuthClientSecret": "secret"
    }
  }
}'

Sample Response​

{
  "meta": {
    "endpointName": "get-an-artist",
    "endpointGroup": "Artists"
  },
  "code": [
    {
      "language": "typescript",
      "value": "const id = '1001';\n\ntry {\r\n  const { result, ...httpResponse } = await artistsController.getAnArtist(id);\n  // Get more response info...\n  // const { statusCode, headers } = httpResponse;\n} catch (error) {\n  if (error instanceof ApiError) {\n    const errors = error.result;\n    // const { statusCode, headers } = error;\n  }\n}\r\n"
    },
    {
      "language": "go",
      "value": "\nctx := context.Background()\n\nid := \"1001\"\n\napiResponse, err := artistsController.GetAnArtist(ctx, id)\nif err != nil {\n    log.Fatalln(err)\n} else {\n    // Printing the result and response\n    fmt.Println(apiResponse.Data)\n    fmt.Println(apiResponse.Response.StatusCode)\n}\n"
    }
  ]
}

Deployment​

The Code Sample API is a Node.js application, making it suitable for deployment on various platforms. Below are step-by-step instructions to deploy it on an Azure App Service configured for Node.js 20 or later using the Azure CLI:

Steps to Deploy on an Azure App Service:​

  1. Prepare the Application:
    Compress the contents of the code-sample-api folder into a .zip file.

  2. Enable Build Automation:
    Open a terminal and run the following command to enable automatic dependency installation during deployment. This ensures that all the dependencies specified in the package.json file automatically get installed during the deployment process.
    Replace the placeholders <group-name> and <app-name> with your resource group and app name: 

    az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true

  3. Deploy the Application Use the command below to deploy the .zip file to your Azure App Service. Replace the placeholders <group-name>, <app-name>, and <zip-file-path> with your resource group, app name, and the path to your .zip file:

    az webapp deploy --resource-group <group-name> --name <app-name> --src-path <zip-file-path>

    For other platforms, refer to their specific Node.js deployment instructions.