Example: Adding an API Legal Agreement

This example walks you through adding a new legal agreement to an existing API in Akana API Platform by using the API rather than the user interface.

This exercise assumes that you already have a valid login for Akana API Platform and are an API admin for the API.

Note: If you added the API, you automatically become the first API Administrator. See POST /api/apis.

Essentially, you'll need to complete these four activities, in sequence:

1. Log in using your authorized user profile you've already set up. Operation: POST /api/login.
2. Upload a legal agreement to the Community Manager developer portal. Operation: POST /content/{path}
3. Publish the legal agreement. Operation: POST /content/{path}.
4. Activate the legal agreement. Operation: POST /api/apis/versions/{APIVersionID}/legals.

Before starting, you will need:

• A valid UserID and password for platform access.
• The APIID.
• The APIVersionID.

For more information about legal agreements, refer to Managing Legal Agreements on the Platform.

To add an API legal agreement in the Akana API Platform using the API

The example below creates a file named eula.txt in the Legals folder for the MyAPIName API created in an earlier exercise (see Example: Adding an API by providing the full API definition). The file content will be the text End-user license agreement. There are no other documents in the folder, so the JSON table of contents for the folder is very simple.

1. Log in via the API, 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. Create the legal agreement in the legals folder of the filesystem for your API on the platform, using the POST /content/{path} operation in the Content service.
   • HTTP method: POST
   • URL: https://{hostname}/content/api/{APIID}/legal/eula.txt?body=End-user%20license%20agreement.
   • Content-Type header: application/x-www-form-urlencoded
3. Publish the eula.txt legal agreement. This creates or updates a Table of Contents for the folder and makes the legal agreement available for activation. Use the POST /content/{path} in the Content service, with the updated TOC JSON file in the body. See below.
   • HTTP method: POST
   • URL: https://{hostname}/content/api/{APIID}/legal/toc.{APIVersionID}.json?body=%7B%22toc%22%3A%5B%22eula.txt%22%5D%2C%22sequence%22%3A%5B%22eula.txt%22%5D%2C%22displayNames%22%3A%7B%7D%7D
   • Content-Type header: application/x-www-form-urlencoded
4. Activate the legal agreement using the POST /api/apis/versions/{APIVersionID}/legals operation. Once it's activated, developers see it and are required to accept it when requesting access to your API. In your API call, use the following, substituting the correct APIVersionID in the URL and the correct APIID in the request body:
   • HTTP method: POST
   • URL: https://{hostname}/api/apis/versions/{APIVersionID}/legals
   • Accept header: text/plain
   • Content-Type header: application/json
   • CSRF header: include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
   • Request Body:

     {
       "ContentPath":"api/{APIID}/legal/eula.txt",
       "PrintContentPath":"api/{APIID}/legal/eula.txt",
       "Name":"EULA",
       "Description":"User License Agreement for the MyAPIName API",
       "AgreementType":"com.soa.acmepaymentscorp.legals.eula"
     }

5. 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