Example: Adding an API by importing an API description document

This example walks you through adding an API to the Akana API Platform by importing an API description document, using the platform API rather than the user interface. This example uses the Swagger Petstore API.

This exercise assumes that you already have a valid login for the Akana API Platform. You can't add an API unless you're an authorized user. Before running the procedures below, go into the user interface to set up your user account.

You'll complete these four activities, in sequence:

1. Log in using the credentials for the user account you've already set up. Operation: POST /api/login.
2. Upload an API description document to the Dropbox. Operation: POST /api/dropbox/readfiledetails.
3. Add an API, referencing the Dropbox ID for the API description document you just uploaded. This also adds the first API version. Operation: POST /api/apis.
4. Log out. Operation: POST /api/login/logout.

Once you've completed Step 3, the APIID is returned in the response and the API is ready for use.

To add an API in the Akana API Platform using the platform API

1. Log in via the POST /api/login operation, using your own email and password in the body of the operation instead of the placeholder values given below.
   • HTTP method: POST
   • URL: https://{hostname}/api/login
   • Accept header: application/json
   • Content-Type header: application/json
   • Request Body:

     {
       "email":"MyEmailAddress",
       "password":"MyPassword"
     }

   The platform API returns the login cookie, which you'll need to send with the request headers for any operation that requires login, and the CSRF cookie, which you'll need to use to put together the CSRF header if required by platform settings (not covered in this exercise: see Example: Using the CSRF header).

2. Upload an API description document to the Dropbox, using the POST /api/dropbox/readfiledetails operation. The document must be locally available. In your API call, use the values below, modifying the URL path as needed, and uploading the API description document.
   • HTTP method: POST
   • URL: https://{hostname}/api/dropbox/readfiledetails
   • Accept header: application/json
   • CSRF header: see Csrf-Token_{fedmemberid}. Include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
   • Login cookie: see AtmoAuthToken_{fedmemberid}.
   • Request Body: the request body is the uploaded API description document, in multipart/form-data format. In the example below, in the Postman client, the file is swagger.json:

     

3. From the API response, get the FileName and DropboxFileId for the uploaded document. An example is shown below.

   

4. Add the API, using the POST /api/apis operation and referencing the DropboxFileId for the API description document that you uploaded. In your API call, use the values below, modifying the URL path as needed. Use the values from the previous response to tailor the request body.
   • HTTP method: POST
   • URL: https://{hostname}/api/apis
   • Accept header: application/vnd.soa.v81+json
   • Content-Type header: application/vnd.soa.v81+json
   • CSRF header: see Csrf-Token_{fedmemberid}. Include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
   • Login cookie: see AtmoAuthToken_{fedmemberid}.
   • Request Body (be sure to update the ServiceName, FileName, and DropboxFileId from the previous response):

     {
       "DLDescriptor":{
         "ServiceDescriptorReference":{
           "ServiceName":"Swagger_Petstore",
           "FileName":"swagger.json",
           "DropboxFileId":1001
         }
       }
     }

5. You should get an HTTP 200 response, with the full API object. An example is shown below (only a portion of the API response shown).

   

6. When done, remember to log out using the GET /api/login/endsession operation. Use the following values:
   • URL: https://{hostname}/api/login/endsession
   • Accept header: application/json

Related Topics