Contact Us 1-800-596-4880
  1. Homepage
  2. APIkit (3.x)

  3. To Retrieve RAML Resources (APIkit 3.8.x)

To Retrieve RAML Resources (APIkit 3.8.x)

The following procedures describe how to retrieve the RAML 0.8 or 1.0 definition of an API generated by APIkit 3.8.x or later. The API must be deployed and accessible, not blocked by a policy, for example.

To Retrieve RAML 0.8

If the API has a RAML 0.8 definition, you can get the root RAML file and all included files in one call. For backward compatibility, you can use either of the following methods to retrieve the RAML code:

  • Retrieve code from APIkit router

  • Retrieve code from API Console

Retrieve RAML 0.8 from APIkit Router

This method involves using a header and a URL ending with /api. You send a header and the URL in a GET request as follows:

  • Header: Accept: application/raml+yaml

  • URL: {scheme}://{host}:{port}/api

Use a client, such as Postman to perform the following steps to retrieve RAML 0.8.

  1. Set up a GET request using the URL ending in the console path. For example:

    http://localhost:8081/api

  2. Set a headers key to Accept and the value to application/raml+yaml. For example:

    *Headers* section with the *Accept

  3. Send the request.

The RAML code and any included files for the API appears in the Body section.

Retrieve RAML 0.8 from API Console

This method requires no headers, just a URL in the following format:

{scheme}://{host}:{port}/console/api/?raml

  1. Set up a GET request using the URL ending in the console path. For example:

    http://localhost:8081/console/api/?raml

    *Body* section with the RAML code.

  2. Send the request.

    The RAML code and any included files for the API appears in the Body section.

To Retrieve RAML 1.0

If the API has a RAML 1.0 definition, you don’t send a header. You can retrieve the root RAML in one call using the GET method. You can retrieve any included resource using the GET method also. The URL syntax is:

{scheme}://{host}:{port}/{console path}/{api resources folder}{optional resource path}/?raml

For example:

  • View the root RAML file example: http://localhost:8081/console/api/?raml

  • View an included file example: http://localhost:8081/console/api/user.schema.json?raml

  • View a RAML fragment example: http://localhost:8081/console/api/types/raml-types.raml?raml

You need to include /api after /console in the URL to be consistent with the RAML file structure inside the Studio project. RAML files in Studio are located under /api/ folder. On the other hand, RAML 1.0 files are served under /console/ path to avoid possible API path collisions with resources defined in the project RAMLs.

The following procedure assumes an API based on these files:

Root RAML in api/api.raml

#%RAML 1.0
title: Retrieve RAML
version: "v1"

/v1/objects:
    get:
        responses:
            "200":
                body:
                  application/json:
                      example: !include example/objects-get-200.json

Included JSON example in objects-get-200.json

[
    {
        "id": 1,
        "name": "One"
    },
    {
        "id": 2,
        "name": "Two"
    },
    {
        "id": 3,
        "name": "Three"
    }
]

  1. Get the root RAML. For example, use the following command:

    curl "http://localhost:8081/console/api/?raml"

    The RAML code appears.

  2. Get the included JSON example. For example, use the following command:

    curl "http://localhost:8081/console/api/example/objects-get-200.json"

    The JSON code appears.

See Also