Working with Physical Services

Add and manage physical services on the Akana API Platform.

Table of Contents

What is a physical service?

A physical service is an API service external to the platform which is not hosted on the platform, but which is set up so that platform APIs can reference it.

In some cases, you might want to reference an external API that isn't hosted on the Community Manager developer portal. For example, you might want one of your hosted APIs to use an external API to gather information used in one of its processes.

You might want to create an API that uses orchestration. Then, within Process Editor, you can use scripting to build a scenario where information is gathered from one or more external APIs, and then manipulated or combined with additional data to produce the desired end result.

When you reference one or more external APIs, you must first set each one up as a physical service.

Note: You can also set up an external API in the normal way, as an API proxied on the platform, and just reference the physical endpoint in your scripts/processes. However, there's no need to do that when you can add it as a physical service.

In the Community Manager developer portal, adding a physical service follows the same basic process as adding an API, although there are some important differences in terms of how the physical service is managed. See How do I add a physical service? and What are the differences between a physical service and a proxied API? below.

How do I add a physical service?

Adding a physical service is very similar to adding an API, but you must choose the Advanced Options and then, in the Pattern field, choose Physical Service. See below.

To add a physical service

  1. Log in to the Akana API Platform.
  2. Click the plus (+) icon in the top menu bar, and choose Add API.
  3. Choose how you want to create your API. For detailed instructions, see How do I add an API? You must provide at minimum a name.
  4. On the right, click the Advanced Options swipe button, as shown below.

    API pattern options

  5. Choose Physical Service.
  6. Click Save. The physical service is created, and the Design page is displayed.

From here you can perform all the functions associated with managing a physical service. See What functions can I perform with a physical service?

What are the differences between a physical service and a proxied API?

Proxy API: When you add an API on the platform as a proxy, which is the default, the API is hosted on the platform. This offers several significant benefits, including:

  • The platform acts as a gateway, allowing you to apply policies and other restrictions and security measures to your API.
  • App developers can connect to your API via the platform.
  • You can track the metrics for your API through the Analytics functions.
  • App developers can access your API documentation via the platform.
  • App developers can test your API via Test Client.
  • You can give users the platform's proxy URL for your API, and keep the actual URL private.
  • You can manage community for your API, including forum, discussions, tickets, ratings, and reviews.
  • You can manage the API Admin team for your API.

Physical Service: When you add an API as a physical service, the API isn't hosted on the platform. It's just there so that you can reference it in scripts and/or processes associated with another API.

Because it isn't hosted, many of the functions and activities associated with managing a proxied API aren't applicable to a physical service. For example, for a physical service, app developers don't see an Overview page and cannot request API access. They can't rate or review the API, or try it out with Test Client.

The table below shows the differences in the user interface, and corresponding access to features and activities, between a physical service and a proxied API.

Left menu options for a physical service: Left menu options for a proxied API:

Physical service: left menu

Proxied API service: left menu

A physical service is referenced by another API; it isn't used directly by app developers. Because of this, there is no need for the following functions that are key to a proxied API:

  • Overview page: This is the page that provides overview information for app developers, and allows contract requests as well as reviews and ratings. All these functions are inapplicable to a physical service.
  • Implementations: Key information that's generally specified for the implementation is set up on the Design page. This includes:
    • Endpoints
    • Policies
    • Certificates
  • Analytics: the physical service is invoked indirectly via orchestration of another API, so the Analytics pages for the physical service are unnecessary. Any activity to and from the physical service is recorded under the metrics for the API that's referencing the physical service.
  • These additional functions are not applicable since app developers are not using a physical service:
    • Forum
    • Test Client
    • Agreements
    • Visibility
    • Apps
    • Followers

What functions can I perform with a physical service?

When you set up an API as a physical service, you can manage the following functions associated with the service:

  • Modify the API design, including resources, model objects, tags, settings, and default media types.
  • Modify the API description.
  • Set up documentation for the physical service.
  • Manage versions for the physical service.
  • Set up and manage one or more endpoints for the physical service.
  • Add, modify, or delete one or more policies associated with the physical service.
  • Add or update certificates for the physical service.

To use the physical service, you can:

  • Reference it in a script used by another API.
  • Reference it in a process used by another API.
  • Use it in defining orchestration for another API.

Where can I see my physical services in the Community Manager developer portal?

You can view your APIs in the Community Manager developer portal on the APIs > My APIs page.

Physical services, which are essentially APIs, are listed with your APIs on the APIs > My APIs page. When you click through you'll see the streamlined feature set associated with a physical service, including the reduced selection of items on the left menu.

How do I modify a physical service?

Once you've added a physical service, you might need to modify one or more aspects of the physical service. In general, the user interface for a physical service mirrors how you manage an API, though many functions relating to an API are not applicable to a physical service. Aspects you might need to modify include:

An example of the Details page for a physical service is shown below.

Physical Service

To edit basic data about a physical service

  1. Log in to the Akana API Platform and go to the Details page for your physical service.
  2. In the top section, click Edit.
  3. Optional: on the left, modify any of these fields:
    • API name: A short and clear name to distinguish the physical service.
    • Summary: A short, plain-text field for internal display.
    • API Description: A concise description of the physical service. Supports Markdown.
  4. Optional: on the right:
    • Change the parent organization by providing the new value in the Parent Organization Name field. Start typing the new organization name in the field. After the first three characters, the platform displays a list of matching organizations for you to choose from. For more information about organizations on the platform, see Organizations.
    • Click the blue dot to display advanced options and modify version number, version name, notes, tags, and/or visibility.
  5. Click Save.

How do I manage endpoints for a physical service?

You can have one or more endpoints for your physical service. You can add, edit, or delete endpoints.

To add an endpoint for a physical service

  1. Log in to the Akana API Platform and go to the Details page for your physical service.
  2. In the Endpoints section, click Edit. The Endpoints page appears, and any current endpoints are displayed.
  3. Click Add Endpoint.
  4. In the Add Endpoint overlay, enter information about the endpoint:
    • Location: a valid URL, the endpoint for the service.
    • Protocol Version: choose from valid values.
    • Require Content-Length Header: if the service requires this header, check the box.
  5. Click Finish.
  6. In the Endpoints overlay, click Finish. The new endpoint is saved.

To edit an existing endpoint for a physical service

  1. Log in to the Akana API Platform and go to the Details page for your physical service.
  2. In the Endpoints section, click Edit. The Endpoints page appears, and any current endpoints are displayed.
  3. Find the endpoint on the list, and click to the right of the line to expand.
  4. Click Edit (pencil icon) to access the Edit Endpoint overlay.
  5. Modify the endpoint values as needed, and then click Finish.
  6. At the Endpoints page, click Finish. The changes are saved.

To delete an endpoint for a physical service

  1. Log in to the Akana API Platform and go to the Details page for your physical service.
  2. In the Endpoints section, click Edit. The Endpoints page appears, and any current endpoints are displayed.
  3. Find the endpoint on the list, and click to the right of the line to expand.
  4. Click Delete (X icon) to delete the endpoint.
  5. At the confirmation message, click OK.
  6. At the Endpoints page, click Finish.

How do I manage policies for a physical service?

Managing policies for a physical service works in the same way as managing policies for an API implementation. You can add, view, and remove policies. For instructions, see Managing Policies for an API Implementation.

For a physical service, policies are in the API Designer: navigate to your physical service > Details page > Policies section > click Edit.

Note: For general information about all policies, see About Policies (Policy Manager help).

How do I manage certificates for a physical service?

Managing certificates for a physical service works in the same way as managing certificates for an API implementation. For instructions, see How do I manage keys and certificates for my API?

For a physical service, certificates are in the API Designer: navigate to your physical service > Details page > Certificates section > click Edit.

How do I add a new version for a physical service?

You can add a new version for a physical service, just as you can for an API. It works in the same way.

For detailed instructions, see How do I add an API version?

How do I delete a physical service?

Deleting a physical service works in the same way as deleting an API.

It's important to make sure that the physical service isn't referenced in an orchestration, script, or process, before deleting it.

When you delete a physical service that has only one version, the physical service is deleted.

To delete a physical service

  1. Log in to the Akana API Platform and go to the Details page for your physical service.
  2. At the top right, click Delete.
  3. At the confirmation prompt, click OK. The physical service is deleted.

How do I manage documentation for my physical service?

Managing documentation for a physical service is the same as managing documentation for an API that's hosted on the platform.

If you upload an API description document, or use API Designer to define the physical service, API documentation will be automatically generated and displayed. You can also upload authored documentation if you need to.

For information relating to managing API documentation, see API Documentation Maintenance.

How do I manage Admins for my physical service?

Managing the Administrator team for an API is exactly the same as managing the Admin team for an API that's hosted on the platform.

the user who creates the physical service becomes the first Admin. A current Admin can invite other users to be Admins, and can remove an existing Admin from the team.

For information relating to managing API Admins, see API Admin Management.