API Portal Version December User Guide

Transcription

1 API Portal Version December 2017 User Guide

2 Copyright 2017 Axway All rights reserved. This documentation describes the following Axway software: Axway API Portal No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway. This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free. Axway recognizes the rights of the holders of all trademarks used in its publications. The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site. Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.

3 Contents Preface 5 Who should read this guide 5 How to use this guide 5 Third-party products and browsers 5 Related documentation 6 Support services 6 Training services 6 Accessibility 7 Screen reader support 7 Support for high contrast and accessible use of colors 7 Updates and revisions 8 Changes in version API Portal overview 9 Key capabilities in API Portal 9 2 User profile 11 Types of users 11 Explore public API Portal 11 Self-register to API Portal 12 Sign in to API Portal 13 Edit your user profile and change password 13 Manage API Portal users and applications 14 Add or edit a user 14 Enable, disable, or delete users 15 Change or reset a password 15 Change the user roles 15 Manage application permissions 15 3 API Catalog 17 View API details 17 View metrics 18 Test an API 18 Test an unsecured API 18 Test a secured API 19 Download an API 21 Download the API definition 21 Axway API Portal User Guide 3

4 Download the client SDK 22 4 Applications 23 Create an application 23 Manage applications 24 Edit application details 24 Manage authentication credentials 25 Share the application 25 Delete the application 25 5 Monitoring 26 Check the metrics for applications 26 Check the metrics for APIs 26 6 Additional features 27 Help Center 27 Discussion forums 27 Documentation 28 Pricing 28 Blog 28 Axway API Portal User Guide 4

5 Preface This guide describes the tasks and activities that you as a client application developer perform when using API Portal to browse and consume APIs. Who should read this guide The intended audience for this guide includes: Application developers. As the actual end users of API Portal, application developers use the APIs listed in API Portal to develop applications. Architects wanting an overview of product capabilities. How to use this guide This guide should be used in conjunction with the other guides in the API Portal documentation set. Before you begin, review this guide thoroughly. The following is a brief description of the contents of each section: API Portal overview on page 9 Provides an overview of API Portal and the key capabilities it offers for developers. User profile on page 11 Describes how to create a user profile for API Portal and sign in, and how to manage user profiles. API Catalog on page 17 Describes how to use API Catalog. Applications on page 23 Describes how to create and manage application in API Portal. Additional features on page 27 Describes how to use Documentation, Help Center, Monitoring, Pricing, and Blog tabs. Third-party products and browsers API Portal has the following requirements for third-party products and browsers: Browser support, as described in the Joomla! documentation. The testing APIs in API Catalog requires a browser with HTML5 support. Axway API Portal User Guide 5

6 Preface Related documentation The API Management Plus solution enables you to create, publish, promote, and manage Application Programming Interfaces (APIs) in a secure and scalable environment. For more information, see the API Management Plus Getting Started Guide. The following reference documents are available on the Axway Documentation portal at Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. Interoperability Matrix Provides product version and interoperability information for Axway products. Support services The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements. support@axway.com or visit Axway Support at See "Get help with API Gateway" in the API Gateway Administrator Guide for the information that you should be prepared to provide when you contact Axway Support. Training services Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: Axway API Portal User Guide 6

7 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support on page 7 Support for high contrast and accessible use of colors on page 7 Screen reader support Alternative text is provided for images whenever necessary. The PDF documents are tagged to provide a logical reading order. Support for high contrast and accessible use of colors The documentation can be used in high-contrast mode. There is sufficient contrast between the text and the background color. The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway API Portal User Guide 7

8 Updates and revisions This guide includes the following documentation changes. Changes in version Added how to explore some sections of API Portal without signing in when Public API is enabled. Axway API Portal User Guide 8

9 API Portal overview 1 Axway API Portal is a self-service developer portal layered on both API Manager and API Gateway. As an application developer, you can use API Portal to browse, consume, build, and test APIs for use in your applications. In addition, API Portal offers several channels, such as FAQs, forums or blogs, that you can use to find out more information. API Portal is part of the Axway API Management Plus solution. For more details, see API Management Plus Getting Started Guide. Key capabilities in API Portal API Portal provides the following capabilities for both internal and external application developers: Self-registration and profile management Application developers can self-register and manage their profiles. Browsing and testing APIs in API Catalog API Catalog contains the APIs that have been registered in API Manager and are available for use. Application developers can browse these APIs and their associated documentation, and invoke APIs using the built-in test capability. Axway API Portal User Guide 9

10 1 API Portal overview Creating and managing applications Application developers can register their applications that use the APIs, and obtain API Key or OAuth or external credentials for their applications. Monitoring API usage Application developers can register their application's use of APIs through graphical real-time charts. This feature requires API Gateway Analytics, because the metrics data is sourced from there. Blog and discussion forums API Portal includes blog and discussion forum Joomla! plugins from a third-party vendor, For more information, refer to: o o EasyDiscuss for discussion forums: EasyBlog for blog: Axway API Portal User Guide 10

11 User profile 2 This section describes how to sign up or sign in to API Portal, and how to edit your user profile. Explore public API Portal on page 11 Self-register to API Portal on page 12 Sign in to API Portal on page 13 Edit your user profile and change password on page 13 Manage API Portal users and applications on page 14 Types of users API Portal has three types of users: API administrator Full control over API Portal (look and feel, configuration, APIs, users). For more details, see the API Manager User Guide. Organization administrators Full control over their organization in API Portal and the users and applications belonging to it. An organization administrator has the same capabilities as an application developer. Application developers API Portal users who write and test applications. Explore public API Portal If your API provider has exposed API Portal for public access, you can explore some sections of API Portal without creating a user account or signing in. Simply click on the Explore button on the API Portal landing page. The user experience in public API Portal is different than when signed in: On the API Portal landing page, the Sign In button is replaced with an Explore button that goes to API Catalog. The items in the main navigation menu have the following changes: o o o API Catalog displays only the APIs and methods configured to be exposed in Public API, but is available normally. The Applications page is available as read-only, and the Usage tab is disabled. The Monitoring and Users pages are unavailable. The user profile information is unavailable. Axway API Portal User Guide 11

12 2 User profile If you do not see the Explore button, your API provider has not enabled this feature, and you must sign in to access API Portal. Self-register to API Portal As an application developer, if you do not have a user account on the API Portal, you can selfregister. 1. Select Sign up. 2. Fill in the required information, and click Sign up: After a successful registration, you see a confirmation message on the page: 3. Follow the instructions in the activation you receive to active your account. You can now sign in to your account. You do not need to create a Joomla! user account separately. When you register on the API Portal, a corresponding Joomla! user account is created automatically. You cannot log in with a Joomla! user account if you are not registered with the API Portal. Axway API Portal User Guide 12

13 2 User profile Sign in to API Portal To log in as an application developer, click the Sign In tab, enter your credentials, and click Sign in. If you do not have credentials, click Sign up to self-register. For more details, see Self-register to API Portal on page 12. Use the Forgot password? link to change your password if you have forgotten it. A temporary password is sent by . Edit your user profile and change password As an application developer, you can view and edit your profile details, such as your password, when you are signed in to API Portal. Axway API Portal User Guide 13

14 2 User profile 1. In the menu at the top of the page, click the profile icon and select My Profile. 2. To edit the profile, click Edit profile, and change the details you want. 3. To change the password, select Change Password, fill in the required details, and click Change Password. 4. To save the changes you have made, click Save changes. Manage API Portal users and applications The API administrator can assign an API Portal user to an organization administrator role in API Manager. Organization administrators are able to manage other API Portal users belonging to their organization. Add or edit a user on page 14 Enable, disable, or delete users on page 15 Change or reset a password on page 15 Change the user roles on page 15 Manage application permissions on page 15 Organization administrators can also manage (for example, enable, disable, or delete) all applications belonging to their organization the same way the application owners can. The organization administrator has an additional menu item, Users, in the API Portal menu. Add or edit a user Organization administrators can add new API Portal users to their organization. They can also edit or remove the users. Axway API Portal User Guide 14

15 2 User profile 1. To create a new user, click Create user, fill in the details, and click Save user. 2. To edit the details of a user, click the user profile, edit the details you want, and click Save changes. Enable, disable, or delete users Organization administrators can control the user profiles in their organization. By default, a user profile is enabled when it is created. 1. To temporarily prevent one or more users from accessing API Portal, select the user profiles you want, and click Disable. 2. To enable disabled user profiles, select the user profiles you want, and click Enable. 3. To permanently remove one or more user profiles from API Portal, select the user profiles you want, and click Delete. Change or reset a password Organization administrators can change or reset a password for an user who has, for example, forgotten the password. 1. Click the user profile you want. 2. To change the password, click Change password, fill in the new password, and click Change password. 3. To reset the password, click Reset password. Change the user roles Organization administrators can change the user roles of the user belonging to their organization to, for example, promote others as organization administrators. 1. Click the user you want to promote. 2. Set Role to Organization Administrator. Manage application permissions Organization administrators can control the application permissions that users in their organization have. In effect, they can share applications with these users. 1. Click the user profile you want. 2. Under Application permissions, click Add applications. 3. Select the applications you want to share with the user, and click Apply. Axway API Portal User Guide 15

16 2 User profile 4. By default, the user can only view shared apps. To change the permissions for an application, toggle the View and Edit buttons next to the application as needed. 5. To remove a user's access to an application, click Remove next to the application. Axway API Portal User Guide 16

17 API Catalog 3 API Catalog in API Portal contains the APIs that are registered in API Manager and are available for use. You can browse APIs and their documentation, and test APIs. This section describes how to use API Catalog in API Portal: View API details on page 17 Test an API on page 18 Download an API on page 21 You can search for the APIS in API Catalog using the API name, description, type, version, or tag. Alternatively, you can filter the list of APIs using tags, or sort it by the API name: View API details To view the details of an API or to test the API, click on the API you want or the Test button. The API details page displays the basic details of the API, such as name, version, base path, tags and available methods. To take a closer look of a method, click the method to expand it. You can view, for example, the following details: Request parameters Response format Axway API Portal User Guide 17

18 3 API Catalog Authentication details Quota Model schema link View metrics On the APIs Catalog page, the View metrics link for a specific API opens the API's details page to the Usage tab, where metrics information for the API is displayed. See Monitoring on page 26 for more information. Test an API You can expand and test API methods listed on the API details page. The required steps depend on whether the API expects authentication or not. This information is shown above the method list. Test an unsecured API on page 18 Test a secured API on page 19 Test an unsecured API If an API does not require authentication, testing the methods is very straightforward. Axway API Portal User Guide 18

19 3 API Catalog 1. Click on the method you want to test. 2. Fill in any values the method requires and select the content type you want. 3. Click Try it out!. The details of the response are shown below the method description. Test a secured API An API exposed in the API Catalog can have the following authorization methods configured in API Manager: API Key authorization OAuth HTTP Basic authentication Invoke Policy You can test any of the configured authorization methods when testing a method. Testing OAuth authentication requires an OAuth access token, see Request an OAuth access token on page 20. Note For Invoke Policy, the option to select credentials is not available, but the description of the API is displayed. 1. Click on the method you want to test. 2. To use the same authorization method for all methods, select Use same credential for all methods. Unselect this option, if you want to choose the authorization method separately when testing each method. 3. Select the key or token you want to use for the authorization. 4. Fill in any values the method requires and select the content type you want. 5. Click Try it out!. API Gateway acts as an authentication and authorization server, and authorizes API Portal to access the API. API Portal returns a formatted result set. If an error occurs, API Portal returns the error status code and error reason details. Axway API Portal User Guide 19

20 3 API Catalog Request an OAuth access token If the API requires OAuth authentication, you must request an access token before trying the API: 1. Click on the method you want to test. 2. Ensure the authorization method is OAuth, and select OAuth client credentials from the dropdown list. 3. Click on the Request token link. 4. Select the permissions for API Portal, and click Authorize. Axway API Portal User Guide 20

21 3 API Catalog The authorization token is displayed as shown below: 5. To discard the authorization token and get a new one, click the Discard token link and repeat the procedure. After you select the authorization type, expand a method and click Try it out! to test it. For additional information about OAuth (OAuth 2.0) deleted access configuration and usage, see the API Gateway OAuth User Guide. Download an API API Catalog provides downloadable content for an API on the API details page: Download the API definition on page 21 Download the client SDK on page 22 Download the API definition An API can offer more than one type of definition. Depending on the API, the following definitions are available: Swagger 2.0 Swagger 1.1 WSDL To download a definition, click on the definition you want in Download definition. Axway API Portal User Guide 21

22 3 API Catalog Download the client SDK Depending on your API provider, you can generate and download a client SDK for an API. The following development platforms are supported: Android ios Node.js Titanium To download a client SDK for a platform, click on the platform you want in Download client SDK. Axway API Portal User Guide 22

23 Applications 4 You can create and manage applications in API Portal. The applications are stored in API Manager. The Applications page lists your client applications, and shows the name, description, and status for each application. The View metrics link provides a quick way to jump to the usage details of the application. To view an application in more detail, click the application to open the Details page. Create an application You can use API Portal to create a simple application that utilizes the APIs in API Catalog. 1. Click Create application. 2. Enter the details for your application. 3. Select the APIs you want to assign to the application. 4. Click Save application. Axway API Portal User Guide 23

24 4 Applications The application is saved in API Manager and visible in the applications list as pending for approval. The API administrator must approve the application before the application is enabled in API Portal. Manage applications You can manage your applications, generate authentication credentials, and share the applications with others. Edit application details on page 24 Manage authentication credentials on page 25 Share the application on page 25 Delete the application on page 25 Edit application details You can edit the basic details of your application, such as the application name, description, and which APIs it uses. 1. Click the application you want to edit to open the application details page. 2. Click Edit application to open the application for editing. Axway API Portal User Guide 24

25 4 Applications 3. On the Details tab, edit the basic details of the application and select which APIs it uses. 4. Click Apply changes to save your changes. Manage authentication credentials If an API your application uses is protected with authentication method in API Manager, the application must authenticate as a client to access the API. For authentication, you must generate credentials for your application. The Authentication tab lists the API Keys, External credentials, OAuth credentials, OAuth scopes for your application. The available authentication methods depend what authentication methods have been configured in API Gateway. 1. Click the application you want and select Edit application. 2. On the Authentication tab, click the authentication method you want. 3. To generate credentials, click Generate. If needed, fill in the required details. 4. To manage existing credentials, find the credential you want to change, and click Actions. The following options are available: Edit: Edit the configuration details of the credentials. View secret: View the secret key generated for the application. Disable: Disable the credentials without deleting them. The credentials are shown as inactive in the credentials list, with an icon indicating they are disabled. Delete: Delete the generated credentials. Share the application You may want to invite other API Portal users to collaborate on your application. You can share the application with them, and define their access level. 1. Click the application you want and select Edit application > Sharing. 2. To share the application with a user, click Add user. 3. Select the users you want to share the application with, and click Apply. 4. By default, the users are only able to view the application, not edit it. To change the access rights of an user, toggle the View and Edit buttons next to the user's name as needed. 5. To remove the access to the application from an users, click Remove next to the user's name. Delete the application 1. On the Applications page, click the application you want to open the Details page. 2. Select Delete application. The Delete application button is also available when editing the application. Axway API Portal User Guide 25

26 Monitoring 5 You can use the graphical real-time charts on the Monitoring page to monitor how your applications use APIs exposed in API Portal. The metrics data sourced from API Analytics. You can view the usage metrics for applications or the API methods your applications use. Check the metrics for applications 1. Click Application Usage. The tab summarizes the processed messages, resolutions, and average processing time for all your applications. 2. To view the metrics on a given point of time, hover the cursor over the line. 3. To change the time range for the metrics, click the time range, select the range you want, and click OK. You can also define a custom time range, for example, if you want to view metrics over a longer period than the presets. 4. To view the metrics for a single application, select the application you want from the table below the usage graph. Click All applications to return to view the metrics for all applications. Check the metrics for APIs 1. Click API Usage. The tab presents API usage metrics for all the API methods exposed in API Portal that your applications use. 2. To view the metrics on a given point of time, hover the cursor over the line. 3. To change the time range for the metrics, click the time range, select the range you want, and click OK. You can also define a custom time range, for example, if you want to view metrics over a longer period than the presets. 4. To view the metrics for a single API method, select the method you want from the table below the usage graph. Click All APIs to return to view the metrics for all applications. Axway API Portal User Guide 26

27 Additional features 6 The API provider can use the following API Portal pages to provide you additional support and other information: Help Center on page 27 Discussion forums on page 27 Documentation on page 28 Pricing on page 28 Blog on page 28 The available options and content may vary depending on your API provider. Help Center Help Center gathers together the API Portal sections that the API provider can use to offer additional information. Help Center provides a central point for links to, for example, FAQs, documentation, discussion forums, or further contact information. Discussion forums The discussion forums in API Portal offers a place to share information and interact with the developer community. To go to the forums, click Help Center > Discussion Forums. Axway API Portal User Guide 27

28 6 Additional features Documentation The API provider may offer additional documentation on, for example, the APIs exposed in the API Portal, terms and conditions for their use, or best practices. The content can include PDF documents, images, and videos. Note The Documentation page is about the content in API Portal. By default, the API Portal User Guide is not included on this page. Pricing The API provider may provide specific pricing information relating to their APIs, products, and services. Blog The API provider may provide blog posts on topics of interest relating to the API Portal and APIs. You can filter the blog posts based on categories, bloggers, or tags. Axway API Portal User Guide 28