Example: Modifying an API Endpoint

This example gives you the high-level sequence of operations to run to modify an API endpoint.

The steps are different depending on whether you're updating the endpoint for:

  • The physical service—the actual API endpoint. For example: http://petstore.swagger.io/v2/.
  • The virtual service—the endpoint that you'll use if your API is hosted on the Akana API Platform. API users send messages to the virtual endpoint, and the platform applies policies, monitors traffic etc. and relays messages to the physical service endpoint. For example: http://api.acmepaymentscorp.com/api10410live.

Before starting, you'll need:

  • A valid UserID and password for portal access.
  • API Admin rights to the API you want to modify.

Operations to run to modify an endpoint for a virtual service

The key operation to run for modifying a virtual service endpoint is: PUT /api/apis/versions/{APIVersionID}/implementations/{ImplCode}/deployments. Other operations in the example below will help you to get authenticated and then to discover any other IDs or information you'll need to successfully run the operation, such as path parameters and request body. If you already have that information you can skip those operations.

Log in

  1. Log in using the authorized user profile you've already set up. Operation: POST /api/login.

    From the response, get your UserID (userFDN value).

Get the API Version ID

  1. Generate a list of your APIs. Operation: GET /api/apis.

    From the response, get the APIVersionID of the API you want to modify. If you're not sure, look in the EntityReferences section for the Title (API version name) and then the guid (APIVersionID).

    Note: If you have the APIID, you could also run the GET /api/apis/{APIID} operation and get the APIVersionID from that (LatestVersionID if there is just one version).

Get the current deployment information

  1. Get information about the current endpoint. Operation: GET /api/apis/versions/{APIVersionID}/implementations/{ImplCode}/deploymentsuggestions.

    ImplCode is Live or Sandbox.

    Copy the response body.

    Note: If the response body is empty, no endpoints have been set up yet.

Modify the endpoint

  1. Update the endpoint. Operation: PUT /api/apis/versions/{APIVersionID}/implementations/{ImplCode}/deployments.

    Use the response from the previous operation in the request body, and modify the endpoint (EndpointPath value). For example, you might change the context path from /api10411live to /api12345live. Do not change the hostname since it is hosted on the Community Manager developer portal. Make sure you change it in all three places:

    • EndpointPath
    • Path
    • Url
  2. Review the response. You'll see that the new endpoint appears in the response, in theEndpointPath, Path, and Url fields for the deployment zone, and the URI field for the endpoint.

Note: To perform this operation in the Community Manager developer portal, go to: API > Implementations > choose implementation > Deployments section > click Edit and update the Context Path field.

Log out

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

Operations to run to modify an endpoint for a physical service

The key operation to run for modifying a physical service endpoint is: PUT /api/apis/versions/{ApiVersionID}/implementations/{ImplCode}/services/{ServiceID}/endpoints. Other operations in the example below will help you to get authenticated and then to discover any other IDs or information you'll need to successfully run the operation, such as path parameters and request body. If you already have that information you can skip those operations.

Log in

  1. Log in using the authorized user profile you've already set up. Operation: POST /api/login.

    From the response, get your UserID (userFDN value).

Get the API Version ID

  1. Generate a list of your APIs. Operation: GET /api/apis.

    From the response, get the APIVersionID of the API you want to modify. If you're not sure, look in the EntityReferences section for the Title (API version name) and then the guid (APIVersionID).

    Note: If you have the APIID, you could also run the GET /api/apis/{APIID} operation and get the APIVersionID from that (LatestVersionID if there is just one version).

Get the Service ID for the physical service

  1. You'll need to get the ID for the physical service you want to update. Operation: GET /api/apis/versions/{APIVersionID}/implementations/{ImplCode}.

    ImplCode is Live or Sandbox.

    In the response:

    • At the top of the response, under Pattern, the ServiceKey value is the service key for the virtual service. This is not the one you want.
    • At the bottom of the response, under ProxyImplementationDetails, the ServiceKey value is the ServiceID for the physical service. You can see that it's the actual endpoint for the API. Save this value.

    For an example, see GET API implementations: sample response.

Get the format of the model object (current information)

  1. Get the current information about the service endpoints. Operation: GET /api/apis/versions/{ApiVersionID}/implementations/{ImplCode}/services/{ServiceID}/endpoints.

    Copy the response body.

    Note: the Uri field shows the existing endpoint for the physical service.

Modify the endpoint

  1. Update the endpoint for the physical service. Operation: PUT /api/apis/versions/{ApiVersionID}/implementations/{ImplCode}/services/{ServiceID}/endpoints.

    Use the response from the previous operation in the request body, and modify the endpoint. Of course, make sure that the new endpoint is valid.

Log out

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