Swagger specification

To document our REST APIs, we utilize the OpenAPI Specification (OAS) available at https://www.openapis.org/. This specification provides a clear and easily readable description of the API and its functionalities. Often referred to as "Swagger" or simply the "specification," it serves as interactive documentation.

The OAS can be exposed through a developer portal, enabling users to make test calls. It supports both YAML and JSON formats, with JSON being automatically converted to YAML. It is essential to make the specification as comprehensive as possible, outlining not only the expected response but also the error responses.

The Swagger specification can be retrieved via an API call, using tools such as Postman (to access the raw swagger.json) or through a web interface like swagger.appythings.nl. The latter presents an interface with configured calls and methods, along with default request and response bodies (if correctly configured in the swagger).

CORS headers

Please note that enabling CORS (Cross-Origin Resource Sharing) headers in the API is essential to permit calls from the browser. This encompasses scenarios where test calls are made using the OpenAPI Specification from the developer portal or through a Swagger UI integration (such as swagger.appythings.nl). To achieve this, consider adding an Assign Message CORS policy to the response flow of the proxy. This policy should be configured to include the necessary CORS headers, allowing for proper cross-origin communication and interaction with the API.

important

WPP has implemented a flow hook that automatically adds CORS headers to the response. This flow hook executes in the Proxy Endpoint Postflow for every API in the environment. As a result, there is no need to manually add CORS headers to each individual API; the flow hook uniformly manages CORS header inclusion across all APIs in the environment. This centralized approach guarantees consistent and efficient handling of CORS-related configurations.

When generating an API from a spec, you have the option to check the "Add CORS headers" box in the security tab. This action automatically includes an Assign Message policy named "Add CORS" in the Target Endpoint PreFlow. However, since this step is no longer necessary, it is advisable to refrain from using this option.

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="AM_addCors">
    <DisplayName>AM_addCORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">*</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage> 

note

The default Apigee policy incorporates the Add element rather than the Set element. The Add element appends headers to the existing ones. Consequently, if a header with the same name already exists, the value specified in the policy is added to the existing header's value. This may result in headers containing the value twice; for example, the "Access-Control-Allow-Origin" header could end up with "**" as its value, potentially leading to conflicts.

To avoid such issues, it is recommended to use the Set element instead. The Set element overwrites an existing header with the same name, replacing its value with the newly specified one. This helps prevent unintended accumulation of values and ensures consistent header behavior.