Example: Adding an API by providing the full API definition
This example walks you through adding an API to the Akana API Platform by using the platform API rather than the user interface. One use of this sequence is to build code that will load multiple APIs via the platform. This could be useful if you are just getting started on the platform and have many APIs.
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.
Essentially, you'll need to complete these two activities, in sequence:
- Log in using the credentials for the user account you've already set up. Operation: POST /api/login.
- Add an API. This also adds the first API version. Operation: POST /api/apis.
Once you've completed the above steps, the APIID is returned in the response and the API is ready for further setup (for example, adding legal agreements, adding operations, adding policies, assigning scopes to operations, adding additional API versions) or for use.
Follow the detailed instructions below.
To add an API in the Akana API Platform using the platform API
- 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).
- Add the API, using the POST /api/apis operation. In your API call, use the values below, modifying the URL path as needed, and filling in your own values for all fields in the Request Body (URL encoding not needed). This is a very simple example, using only a few values to create an API in the platform.
- 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: include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
- Request Body (Key values are: API Name and Description, Version Name and Description, endpoint URI (target URL), and, for Proxy API, endpoint URI (CNAME) in the Endpoints node):
{ "Name":"ACME Payments API", "Description":"Payments API for ACME customers.", "Visibility":"Public", "PictureID":"", "APIVersion":{ "Visibility":"Public", "Name":"1", "ResourceLevelPermissionsSupported":true, "Description":"First version", "TargetAPI":{ "Endpoints":{ "Endpoint":[ { "Uri":"http://www.acmepayments.com/apisb", "Category":"Sandbox" }, { "Uri":"http://www.acmepayments.com/api", "Category":"Production" } ] }, "Type":"shttp", "Operations":{ "Operation":[ { "Method":"GET", "Path":"/payments/{paymentid}", "Input":[ { "Name":"paymentid", "Type":"path" } ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"getPayment" }, { "Method":"GET", "Path":"/payments/payments", "Input":[ ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"listPayments" }, { "Method":"POST", "Path":"/payments", "Input":[ ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"addPayment" }, { "Method":"DELETE", "Path":"/payments/{paymentid}", "Input":[ { "Name":"paymentid", "Type":"path" } ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"deletePayment" } ] }, "Policies":{ "Policy":[ ] }, "DefaultProfile":"Any in and out" }, "Endpoints":{ "Endpoint":[ { "Uri":"http://acme-payments-api.10.1.20.137:9901/", "Category":"Production", "CName":"acme-payments-api.10.1.20.137", "DeploymentZoneRule":"1b16623b-1609-4664-9900-06f8441bdefault-http0" }, { "Uri":"http://acme-payments-api.10.1.20.137:9901/", "Category":"Sandbox", "CName":"acme-payments-api.10.1.20.137", "DeploymentZoneRule":"1b16623b-1609-4664-9900-06f8441bdefault-http0" } ] }, "Operations":{ "Operation":[ { "Method":"GET", "Path":"/payments/{paymentid}", "Input":[ { "Name":"paymentid", "Type":"path" } ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"getPayment" }, { "Method":"GET", "Path":"/payments/payments", "Input":[ ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"listPayments" }, { "Method":"POST", "Path":"/payments", "Input":[ ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"addPayment" }, { "Method":"DELETE", "Path":"/{path:.+|}", "Input":[ { "Name":"path", "Type":"path" } ], "InputContentType":"*/*", "OutputContentType":"*/*", "FaultContentType":"*/*", "Name":"deletePayment" } ] }, "Type":"shttp", "ProductionEndpoint":"http://acme-payments-api.10.1.20.137:9901/", "SandboxEndpoint":"http://acme-payments-api.10.1.20.137:9901/", "Tag":[ "ACME", "payments", "" ], "Policies":{ "Policy":[ ] }, "DefaultProfile":"Any in and out", "ProductionAnonymousAccessAllowed":false, "SandboxAnonymousAccessAllowed":false, "ProductionEndpointAccessAutoApproved":false, "SandboxEndpointAccessAutoApproved":true } }
- You should get an HTTP 200 response, with the full API object.Take the APIID and APIVersionID returned in the response object; you will use these later.
- 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