Documentation Documentation

Import APIs

Tyk supports importing both API Blueprint and Swagger JSON definitions from either the Gateway or the Dashboard. Tyk will output the converted file to to stdout. Below are the commands you can use to get Tyk to switch to command mode and generate the respective API definitions for both API Blueprint and Swagger files.

Import APIs via the Gateway

Using API Blueprint

Tyk supports an easy way to import Apiary API Blueprints in JSON format using the command line.

Blueprints can be imported and turned into standalone API definitions (for new APIs) and also imported as versions into existing APIs.

It is possible to import APIs and generate mocks or to generate White Lists that pass-through to an upstream URL.

All imported Blueprints must be in the JSON representation of Blueprint's markdown documents. This can be created using Apiary's Snow Crash tool.

Tyk outputs all new API definitions to stdout, so redirecting the output to a file is advised in order to generate new definitions to use in a real configuration.

Importing a Blueprint as a new API:

Create a new definition from the Blueprint:

./tyk --import-blueprint=blueprint.json --create-api --org-id=<id> --upstream-target="http://widgets.com/api/"

Importing a definition as a version in an existing API:

Add a version to a definition:

./tyk --import-blueprint=blueprint.json --for-api=<path> --as-version="version_number"

Creating your API versions as a mock

As the API Blueprint definition allows for example responses to be embedded, these examples can be imported as forced replies, in effect mocking out the API. To enable this mode, when generating a new API or importing as a version, simply add the --as-mock parameter.

Using Swagger

Tyk supports importing Swagger documents to create API definitions and API versions. Swagger imports do not support mocking though, so sample data and replies will need to be added manually later.

Importing a Swagger document as a new API

Create a new definition from Swagger:

./tyk --import-swagger=petstore.json --create-api --org-id=<id> --upstream-target="http://widgets.com/api/"

Importing a swagger document as a version into an existing API

Add a version to a definition:

./tyk --import-swagger=petstore.json --for-api=<path> --as-version="version_number"

Mocks

Tyk supports API mocking using our versioning use_extended_paths setup, adding mocked URL data to one of the three list types (white-list, black-list or ignored). In order to handle a mocked path, use an entry that has action set to reply:

"ignored": [
  {
    "path": "/v1/ignored/with_id/{id}",
    "method_actions": {
      "GET": {
        "action": "reply",
        "code": 200,
        "data": "Hello World",
        "headers": {
          "x-tyk-override": "tyk-override"
        }
      }
    }
  }
],

See Versioning for more details.

Import APIs via the Dashboard API

Import API - Swagger

Property Description
Resource URL /api/import/swagger/
Method POST
Type None
Body None
Param None

Sample Request

POST /api/import/swagger/
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
{
  "swagger": "{swagger data...}",
  "insert_into_api": false, 
  "api_id": "internal API id",
  "version_name": "yourversionname",
  "upstream_url": "yourupstreamurl"
}

Parameters:

  • insert_into_api: If set to true the import will replace an existing API. Setting to false will import into a new API.
  • api_id: The internal MongoDB object id for your API.
  • version_name: Your versioning convention name for the imported API.
  • upstream_url: The URL the API is served by.

Sample Response

{
  "Status": "OK",
  "Message": "API Imported",
  "Meta": "new_api_id"
}

Import API - Blueprint

Property Description
Resource URL /api/import/blueprint/
Method POST
Type None
Body None
Param None

Sample Request

POST /api/import/blueprint/
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
{
  "blueprint": "{blueprint data...}",
  "insert_into_api": false, 
  "api_id": "internal API id",
  "as_mock": false,
  "version_name": "yourversionname",
  "upstream_url": "yourupstreamurl"
}

Parameters:

  • insert_into_api: If set to true the import will replace an existing API. Setting to false will import into a new API.
  • api_id: The internal MongoDB object id for your API.
  • as_mock: If set to true, enables our mocking support for Blueprint imported API. See Mocks above for more details.
  • version_name: Your versioning convention name for the imported API.
  • upstream_url: The URL the API is served by.

Sample Response

{
  "Status": "OK",
  "Message": "API Imported",
  "Meta": "new_api_id"
}

Import APIs via the Dashboard

Step 1: Select "APIs" from the "System Management" section

API listing page link location

Step 2: Click "IMPORT API"

Add API button location

Tyk supports the following import options:

  1. From an Existing Tyk API definition
  2. From a Apiary Blueprint (JSON) file
  3. From a Swagger (JSON) file

To import a Tyk Definition, just copy and paste the definition into the code editor.

Import Tyk Definition

For Apiary Blueprint and Swagger, the process is the same. For example:

Click the "From Swagger (JSON)" option from the pop-up

Import popup

Step 3: Enter API Information

You need to enter the following information:

  • Your Upstream Target
  • A Version Name (optional)
  • Copy your Swagger based API into the code editor

Step 4: Click "Generate API"

Your API will appear in your APIs list. If you select EDIT from the ACTIONS drop-down list, you can see the endpoints (from the ENDPOINT DESIGNER) that have been created as part of the import process.