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.
-
Set up a GET request using the URL ending in the console path. For example:
http://localhost:8081/api
-
Set a headers key to Accept and the value to application/raml+yaml. For example:
-
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
-
Set up a GET request using the URL ending in the console path. For example:
http://localhost:8081/console/api/?raml
-
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" } ]
-
Get the root RAML. For example, use the following command:
curl "http://localhost:8081/console/api/?raml"
The RAML code appears.
-
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.