Onboarding APIs

The trading engine Onboarding APIs support a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations.

For detailed documentation on each resource and its parameters, see the dynamically generated API documentation available on your host: https://<host>:<port>/apidocs.

This chapter includes information about the REST APIs used in:

  • Creating communities
  • Adding partners
  • Adding and configuring partner services
  • Adding and configuring agreements
  • Adding and configuring components

User authentication and access rights

In order to use the B2Bi REST API, the user must log on with the credentials (user name and password) of an account that is granted the permission to access the API interface.

By default, "admin" users have all access permissions, so can freely use the REST API.

An error message is displayed indicating an authorization failure if the user attempts to perform a REST API operation:

  • With a user account that is not authorized for REST API access
  • With an invalid user name or password

For a B2Bi implementation, there are two options for user access management:

  • Manage user access in B2Bi
  • Manage user access in PassPort

For a B2Bi implementation, for user access management you can use Manage user access in B2Bi.

Manage user access in B2Bi

When B2Bi native user-access management is used, user accounts are managed by an administrator in the B2Bi graphical user interface. User access rights are granted through the attribution of "roles" and "permissions". REST API users must be given the permission "Access APIs".

For detailed information on how to manage B2Bi users, roles, and permissions, see the B2Bi Administrator Guide.

Manage user access in PassPort

If you are using PassPort as your B2Bi user access-management tool, user accounts are managed by an administrator in the PassPort user interface. User access rights are granted through the attribution of "roles" and "privileges". REST API users must be given the privilege "Access APIs".

For detailed information on how to manage users, roles, and privileges in PassPort, see the PassPort documentation.

When PassPort is the user access manager, REST API users must log in with a user name containing the domain. For example, if the user account is User1 and the domain is MyCompany, the user name for API access is "User1@MyCompany".

Scope of the "Access APIs" permission

A user who is attributed the "Access APIs" permission has full access to all of the resources and methods provided by the REST API. This access is not limited by any additional role restrictions that the same user may have when working in the B2Bi UI.

Password reset requirement

There are two special cases, related to user administration, in which the user may be refused access with the error message:

"Password is expired, unable to perform login request. You need to reset the password".

This message occurs when the use administrator:

  • Has recently created the user and selected the option "Force user to reset password upon initial login".
  • Has recently modified the user account and selected the option "Force a password change after this user's next login".

In either of these cases, before the user can log in to the REST API interface, he or she must first log into the B2Bi UI and reset the account password when prompted.

Swagger interface

Swagger is automatically installed as a light-weight REST client for executing REST API operations on B2Bi servers and viewing API-related documentation.

Open Swagger

There are two ways to open the Swagger interface for use with B2Bi REST API:

Direct method (recommended):

Open a browser and enter the URL: https://<host>:<port>/apidocs/ui

Indirect method:

  1. Open the REST API interface page from a browser by entering the URL: https://<host>:<port>/apidocs
  2. On the REST API page, in the "Swagger" section, click the Swagger UI link.

Use Swagger

The Swagger interface provides the same set of resources and operations for B2Bi server management as the generic B2Bi REST API interface. Swagger offers simplified usability and the clear display of use descriptions.

Authentication requirements are the same as for any B2Bi REST API use. For the first operation you execute on a B2Bi server you are required to provide a username and password. Thereafter, you can continue to execute operations without additional authentication for the session.

Known limitations

User can continue to execute operations after logout

When using Chrome and Firefox browsers, after logging out of a Swagger session, users can call operations, as though they had not logged out. This problem occurs because these browsers remember, and automatically provide, the login credentials. Credentials are cleared from memory when the browser window is closed.

User cannot log in using the login method

The REST login method asks for the authorization header which is a single string composed of a hash of the username and password. In most cases, the user will only know his username and password.

Workaround: The user can directly call any operation from the Swagger interface. This triggers the login, causing the browser to display a user-friendly prompt for the username and password.

User cannot import or export certificates in Swagger

When a user accesses the import operation, it is not possible to specify the path to the certificate to be imported. For the export operation, it is not possible to specify where the exported file is to be saved. This is because the Swagger client does not support the “application/octet-stream” content-type used by the import/export operations in the B2Bi REST API.

Onboarding project planning

As you navigate through the dynamic documentation for each resource, notice that each primary resource contains a series of sub-resources that correspond to B2Bi objects applicable to specific protocols. In some cases there are multiple sub-resources for a B2Bi object type.

As you develop your Onboarding project plan, be sure to:

  • Read the dynamic API documentation thoroughly. Note, different methods (GET, POST, UPDATE/PUT, DELETE) apply for each sub-resource.
  • Evaluate all resources and sub-resources carefully and test in a sandbox environment.
  • Consider consulting with Axway Professional Services.

See REST API support for details.

Related Links