Important Note
This space contains files and text snippets that are used throughout the Scheer PAS documentation.
This content is not meant to be read independently from the rest of the documentation.
- Created by Kirstin Seidel-Gebert, last modified by Annegret Bernhardt on Apr 02, 2024
Excerpts from Version 23.2
Oops, it seems that you need to place a table or a macro generating a table within the Table Filter macro.
The table is being loaded. Please wait for a bit ...
Chapter | Name | Excerpt | Usage |
---|---|---|---|
APIs | info_open_api_documentation | Adding or removing policies does not enrich the Open API documentation. You need to adjust your documentation manually. For more information on REST documentation and how to add documentation to xUML services, refer to Bridge Guide > Documenting a REST Service. | |
APIs | info_testing_apis | Testing of API configurations is only possible with REST APIs that are coming with an OpenAPI Specification. | |
APIs | setting_validity_api | This setting is valid for all versions of the API. |
|
Clients | setting_validity_client | This setting is valid for all versions of the client. |
|
Developer Portal | access_documentation_and_definiton | You can also access the API Documentation and Download the API definition file here. | |
Developer Portal | api_documentation | Click API Documentation to access the Swagger UI where you can test the API (refer to Testing APIs for further information). | |
Developer Portal | confirm_delete | For security reasons, you need to confirm the deletion. | |
Developer Portal | display_open_api_definition | Displays the Open API definition (Swagger) and allows for making test calls if the API is available. |
|
Developer Portal | download_open_api_definition | Downloads the API definition file. |
|
Developer Portal | latest_api_version | If more than one version of the API is available, the latest version will be displayed on top. To see the details of earlier versions, expand the labels below the open details page. | |
Developer Portal | portal_copy_to_clipboard | Click Copy to copy the key to the clipboard. |
|
Developer Portal | sign_up_client_created | After a successful creation, your client is displayed in the box below. Click Next to continue. | |
Developer Portal | sign_up_create_client | Now follow the wizard through some simple steps:
Click Create. | |
Developer Portal | sign_up_multiple_organizations | If your user has permission to use or create clients in various organizations, a different view will be displayed:
Click Next to continue. | |
Developer Portal | sign_up_my_clients_tab | Tab My Clients displays an overview of your clients and their contracts. Your new client is displayed and labeled as Awaiting Approval. Refer to Handling Approval Requests for detailed information about the approval process in API Management. | |
Developer Portal | sign_up_request_approved | As soon as an administrator approved your request, you will get a notification. Now you can start using the API. | |
Developer Portal | sign_up_success | A success message is displayed in the Developer Portal. If approval is required for the API you subscribed to, you now have to wait for the approval. If you want to check your newly created client, switch to the My Clients tab. | |
Developer Portal | sign_up_summary | In step 2, the summary displays the API-related information. Click Confirm to send your request. API Key and Endpoint will be provided to you after your request is approved. | |
General | adding_versions | To create a new version, click New Version (refer to The Concepts of API Management > Versioning for detailed information). | |
General | api_learn_more | Click Learn More on the API that you want to consume. This will open the API's details. | |
General | create_button | No matter where you are in the API Management, the Create button is always displayed at the bottom right and opens the creation menu. | |
General | creation_wizard | In the next step, you need to enter the following mandatory settings:
You can enter numbers and text in field Version. Refer to The Concepts of API Management > Versioning for detailed information. You can then enter a description. The description is optional and can also be entered or changed later on the details page. Click Next to continue. | |
General | enable_delete_button | Option Delete is only enabled if you activate the checkbox. | |
General | info_mail_notifications | The notifications can also be sent by by email. This feature must be enabled during the the setup of your Scheer PAS installation. Ask your Scheer PAS administrator for help. | |
General | info_metrics | Refer to Metrics for detailed information about the available options. | |
General | info_rights_management | In API Management, a user can see all APIs for which he has explicit permissions (roles Viewer and Editor). The permissions are assigned in the corresponding organizations, refer to Administrating Organization Members > Applicable Roles. | |
General | organization_preset | In that case, the organization is already set in the wizard. | |
General | plan_sign_up | In the Plans section, you find all available plans for the API and information on whether approval is required for a plan. Click Sign Up on the plan you want to register for. | |
General | successful_deletion | A toast message indicates successful deletion. | |
General | tip_entity_deletion | Expert Advice Do not delete APIs, plans, or clients and recreate them if you want to change policies or settings. Instead:
| |
General | tip_infos_about_policies | Refer to chapter Policies for an overview of the standard policies supplied with Scheer PAS API Management. Page Attaching Policies explains how to attach and configure a policy. | |
General | tip_navigation | For detailed information about navigating and filtering the list refer to Working With the API Management. | |
General | tip_visibility_concept | For detailed information about the visibility concept, refer to The Concepts of API Management. |
|
Organizations | organization_best_practices | Expert Advice We recommend the following best practices regarding organizations:
| |
Plans | info_deleting_locked_plans | You cannot delete a locked plan. Locked plans are deleted only when the entire organization is deleted. | |
Plans | locked_plan_unchangeable | Once a plan is locked, it cannot be revised anymore. However, you can still create a new version of this plan. |
|
Plans | setting_validity_plan | This setting is valid for all versions of the plan. |
|
Policies | claim_availability | All standard claims, custom claims and ID token fields are available (case sensitive). A special value of access_token will forward the entire encoded token. Nested claims can be accessed by using the JavaScript dot syntax (e.g: address.country, address.formatted). | |
Policies | cors_policy_chain_text | API Management sets the CORS headers in the following order:
For detailed explanations about Cross-Origin Resource Sharing (CORS) visit the official Mozilla documentation. | |
Policies | info_cors_list_input | Confirm each field input with Enter to create various list entries. |
|
Policies | info_java_syntax | Regular expressions must be written in Java syntax. | |
Policies | info_self_signed_certificates | Self-signed certificates are currently not supported. | |
Policies | info_stateful_request_payload | If you want to cache POST requests, you have to enable stateful request payload inspection in the settings of your API. |
|
Policies | keycloak_tokens | With PAS 23.1.1, the Scheer PAS installation comes with the default Keycloak client api-management-oauth. Keycloak clients are entities that can request Keycloak to authenticate a user. In most cases, Keycloak clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. However, clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network. If you use the Keycloak OAuth policy, we recommend to check against the default client api-management-oauth. Expert Advice If you need to create your own client in Keycloak, visit the official Keycloak documentation for further information. | |
Policies | keycloak_tokens_usage | You have to send the received token with each request as authorization header. If you use the PAS internal request UI (Swagger UI), the token is set automatically. Example: Example API Request curl --location 'https://scheer-acme.com/acme-test/gateway/test/hello-oauth/1.0' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' | |
Policies | note_allowlist_blocklist | An IP Blocklist policy overrides an IP Allowlist policy. | |
Policies | note_enable_option | It is stongly recommended to enable this option. | |
Policies | policies_best_practices | Expert Advice We recommend the following best practices regarding policies:
| |
Policies | policies_table_handling | Click Add to create more rows in the table. Click Delete to remove selected rows. | |
Tips and Tricks | attaching_a_policy | A wizard supports you during policy configuration. Refer to Attaching Policies for a step-by-step guide. |
Excerpts up to Version 23.1.1
Some API Management excerpts are saved within the documenation, see API Management excerpts managed directly in the documentation for an overview.
Oops, it seems that you need to place a table or a macro generating a table within the Table Filter macro.
The table is being loaded. Please wait for a bit ...
Chapter | Name | Excerpt | Usage |
---|---|---|---|
Policies | api_behind_proxy | Please disable the TLS check if you are using Scheer PAS 21.1 or a newer version, because all PAS components are running behind a proxy server. | |
Policies | api_blacklist_whitelist | An IP Blocklist policy overrides an IP Allowlist policy. | |
Terms & Definitions | api_contracts_and_keys | Only public APIs can be accessed by any consumer. The only way for a client to consume a private API is by using an API contract. An API contract is a link between a client and an API through a plan offered by that API. API contracts can only be created between clients and published APIs which are offered through at least one plan. An API contract cannot be created between a client and a public API. When an API contract is created, the system generates a unique API Key. This key is unique per client and the same for all contracts of this client. All requests made to the API by a client through the gateway must include this API Key. The API Key is used to create the runtime policy chain from the policies configured on the API, plan and client. You can forward the X-API-Key to the service using the API Key policy. However, you cannot define your own value for the X-API-Key, since the gateway uses the key to identify the clients. | |
General Notes, Infos, Tips | api_displayed_when_published | This tab is only visible for published APIs. |
|
General Notes, Infos, Tips | api_displayed_when_registered | This tab is only visible for registered clients. | |
Developer Portal | api_doc_and_definition | The API Documentation button and a button to download the API definition file are also available here. | |
Developer Portal | api_documentation_button | The API Documentation button grants access to the Swagger UI where the user can test the API (refer to Testing APIs for further information). | |
Policies | api_enable_option | It is strongly recommended to enable this option. | |
General Notes, Infos, Tips | api_link_to_policy_page | Refer to Policies for an overview of the standard policies supplied with Scheer PAS API Management. Refer to Assigning Policies for detailed explanations on how to configure a policy. | |
Policies | api_move_policies | The order of the policies is important. The order in which the policies appear in the user interface determines the order they will be applied at runtime. You can drag a policy up and down the list to change the order: | |
General Notes, Infos, Tips | api_my_all_hint | If you want to edit API Management elements, you need to access them via the My... menu items (refer to "My" API Management items). | |
Clients | api_registered_client | Before the client is registered with the runtime gateway, it is not possible to make requests to backend APIs on behalf of that client. | |
General Notes, Infos, Tips | api_save_when_finished | Do not forget to click the Save button when you have finished. |
|
Developer Portal | api_version_label | If more than one version of the API is available, the latest version will be displayed on top. To see the details of earlier versions, expand the labels below the open details page. | |
General Notes, Infos, Tips | api_version_number_note | You can enter numbers and text in the Version field which allows the use of version numbers (e.g. 1.0, 2.1 ...) as well as version descriptions (e.g. Gold, Super etc.). | |
APIs | api_visibility | Use the drop-down list to define which user group can browse the API and the corresponding plan. This affects the view in the API Management itself as well as in the API Developer Portal:
For detailed information about the visibility concept, visit page The Concepts of API Management. |
|
General Notes, Infos, Tips | api_work_with_items | Click to add a new item to a list, click to show/hide the list of items. | |
Developer Portal | approver_confirmation | For security reasons, the approver needs to confirm his choice. | |
Developer Portal | confirm_deletion | For security reasons, you need to confirm the deletion. | |
Developer Portal | copy_to_clipboard | Use icon to copy the key to the clipboard. |
|
Developer Portal | corresponding_message_in_portal | The user gets a corresponding notification in the API Developer Portal. | |
Policies | cors_policy_chain | API Management sets the CORS headers in the following order:
For detailed explanations about Cross-Origin Resource Sharing (CORS) visit the official Mozilla documentation. | |
Terms & Definitions | definition_api | APIs in API Management represent real back-end APIs (Application Programming Interfaces). An API is also known as a service, meaning anything that can be invoked remotely by some sort of client. API Management provides a way to turn unmanaged (raw) back-end APIs into managed APIs by attaching policies to them. Every managed API can be published as Public API or Private API or both:
In API Management, users can create new APIs manually or easily import them from the API Catalog. | |
Terms & Definitions | definition_client | The client is the consumer of the API:
| |
Terms & Definitions | definition_contract | A contract relates a client to an API, using a plan. | |
Terms & Definitions | definition_organization | Almost everything in the API Management data model exists in the context of an organization:
| |
Terms & Definitions | definition_plan | A plan is a set of policies that defines the level of service API Management provides for an API.
| |
Terms & Definitions | definition_policy | Policies are at the lowest level of the data model, but they are the most important concept: A policy is a rule or a set of rules API Management uses to manage access to your APIs.
| |
Developer Portal | description_api_definition_download | Downloads the API definition file. |
|
Developer Portal | description_api_documentation | Displays the Open API definition (Swagger) and allows for making test calls if the API is available. |
|
Developer Portal | details_page_public | On the details page of a Public API, users can find further information about the API such as an extended description and the public endpoint. | |
Notifications | info_enable_mail_notifications | The notifications can also be sent by by email. This feature must be enabled during the the setup of your Scheer PAS installation. Ask your Scheer PAS administrator for help. | |
Plans | locked_plans | Once a plan is locked, it cannot be revised anymore. However, you can still create a new version of this plan. | |
Administration | manage_users | API Management uses the Identity Management to manage its users. This tool can manage users for multiple applications. Data for each application is stored in so called "realms":
Thus, you need to have to separate admin accounts: one for Identity Management, and one for API Management. | |
Plans | note_on_plan_usage | Only locked plans can be used by APIs in the organization. Refer to Locking a Plan for more information. | |
General Notes, Infos, Tips | note_read_confirmation_dialog | Please read the confirmation dialog carefully. | |
Policies | note_require_true | Make sure that this option is true if you want to use this policy for authentication. | |
Policies | proxy_x_real | In the default setup the gateway runs behind a proxy. In the default scenario there is no need to add the header X-Real-IP in the custom header field IP Address HTTP Header. | |
Support | support_overview |
| |
Policies | swagger_definition_changes | Adding or removing policies does not enrich the Open API documentation. You need to adjust your documentation manually. | |
Clients | swagger_ui | For more information about the functions of the Swagger UI, go to the Swagger homepage. | |
Administration | test_gateway_nok | If the configuration is invalid, an error message will be shown including further information about the error itself: | |
Administration | test_gateway_ok | If the gateway configuration is correct, you will get a success message: | |
APIs | testing_api_with_swagger | Testing of API configurations is only possible with REST APIs that are coming with an OpenAPI Specification. | |
Metrics | tipp_elaborated_metrics | PAS 22.1 For more elaborated metrics, have a look at the Log Analyzer which offers a default dashboard visualizing API Management insights. |
|
General Notes, Infos, Tips | use_breadcrump | Use the breadcrumb menu at the top of the page for guidance. |
|
Organizations | version_note_api_org_creation | From PAS 22.1 all API Management users can create new organizations. In earlier versions, only users with role Administrator had been able to create organizations. |
API Management excerpts managed directly in the documentation
Chapter | Excerpt Name | Page of the Original | (Re-)Usage |
---|---|---|---|
Administration | data_export | ||
Administration | backup | ||
Administration | data_import | ||
Administration | restore | ||
Administration | keycloak_login |
| |
Policies | policy_overview_table | ||
Policies | info_post_requests |
| |
Metrics | api_metrics | ||
Metrics | client_metrics | Metrics | |
Some Common API Management Use Cases | page_content | Securing Designer Services via API Management |
- No labels