Complete support for multiple responses has been added to API Transformer across all major formats like OpenAPI, RAML, API Blueprint, etc. This means a major reduction in loss of information related to responses when converting between various formats. Note, that these changes can also affect how your import in the Dashboard works.
These changes will only affect you if you choose to re-transform or re-import your files. Please review this changelog carefully and make any adjustments to your API description files, if necessary, to avoid any issues.
What Was Supported Before?
Previously, we supported the following in terms of responses:
- A single success response definition per endpoint (status code in the range 200-208).
- A single body content definition per response.
- Multiple client/server error response definitions (in the range 400-599) with limited support for error response body schema’s details excluding array information, primitive type information, nullable information, examples, etc.
- For response definitions involving status code ranges (as supported in OpenAPI v3.0), only information of supported response codes falling in that range were loaded independently during import/transformation as there was no support for ranges syntax.
- A single auto-generated test case per each supported response code.
Until now, full support for this feature was only available for our RAML v1.0 import/transformation as you can see from the changelog here and unavailable in other formats.
What’s New?
We have now added as well as improved existing support for multiple responses in all major formats where applicable. These formats include Postman (v1.0, v2.0), OpenAPI/Swagger (v1.2, v2.0, v3.0), RAML (v1.0, v0.8), WADL, WSDL, API Blueprint and HAR. These changes will affect how your transformation and may also affect how your import in the Dashboard works.
Currently, these changes will only be available in API Transformer. A release date for SDKs/Docs will be announced later.
Complete Response Information Will Be Imported/Transformed
For all responses with status codes in the range 100-599, we now support:
- All possible content-types of a response with complete information related to its respective body schema definition.
- Complete information of headers and examples associated with the response.
Better Support for Error Responses
Details related to error responses (of range 400-599) that were previously lost during transformation/import e.g. primitive type information, array information, enumeration type details, examples, etc. will now be loaded.
Changes to Imported/Transformed Models
Additional types/models may be added
Additional types may be added upon transformation/import due to the following reasons:
- Loading of additional responses in the range 1XX or 3XX.
responses:
'100':
description: Continue Response
content:
application/json:
schema:
type: object
properties:
id:
type: number
'302':
description: Found Response
content:
application/json:
schema:
type: object
properties:
operation:
type: string
Previously, only status codes in the range 200-208 and 400-500 were supported, but now all status codes in the range 1XX and 3XX are supported as well. As a result of loading these additional responses, additional types/models may be generated in some cases especially where inline schemas are involved.
- Loading of additional success responses.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
id:
type: number
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
operation:
type: string
Previously, in case multiple success response definitions were present [of range 200-299], only the first one was picked and the rest were ignored e.g. in the example above status code 200 is loaded while the status code 201 was ignored. Now, as a result of loading all status codes additional types may be loaded in such cases especially if the schemas are defined in-line.
- Loading of multiple body content definitions.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
id:
type: number
text/plain:
schema:
type: string
enum:
- one
- two
- three
As we now support all possible content-types for a single response, so loading associated schema definitions may result in additional models.
- Loading of complete information for error responses [of range 400-599].
responses:
'400':
description: Successful Response
content:
application/json:
schema:
type: object
required:
- message
- code
properties:
message:
type: string
code:
type: integer
minimum: 100
maximum: 600
An error response model is loaded as a special type of model in APIMatic i.e. Exception. This helps treat errors in a better way in SDKs. However, to facilitate better transformation in API Transformer and to reduce loss of information, error models will now also be added as Structure type models in addition to Exception type models. This may result in additional models upon importing your API specification especially if your error response definition involves inline schemas.
Since enumeration type error responses are now supported as well, this may also result in new models of type Enumeration upon import.
Names of imported inline models/types may change
Inline schemas (not globally defined) are imported in APIMatic with the names inferred from the field/parameter names in which the schemas are defined. To prevent duplication of model names, a number is usually appended to the end of the conflicting model’s name. Since new models may get added as described in previous points, the model names for loaded inline schemas may change in some cases e.g. a type previously named as Status1 may become Status2 if an additional type of the same name gets loaded before it.
Changes to Auto-Generated Test Cases
Multiple test-cases will now be generated against each response’s status code (in the range 200-208) and for every possible body content definition in that response. In addition to this, the following changes will also take place:
- Test cases will no longer be auto-generated for error responses (in the range 400-599).
- Invalid
Content-Typeheaders e.g. those containing media type ranges (using the * wildcard) will no longer be added to expected headers of auto-generated test cases.
Support for Status Code Ranges [1XX, 2XX, 3XX, 4XX, 5XX]
Specifying status code ranges using uppercase wildcard characters ‘X’ in the status codes is a feature supported by OpenAPI 3.0 and is now supported by us as well.
responses:
'2XX':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
id:
type: number
For exporting to formats that do not support ranges, only valid status codes from the range will be exported e.g. if the range specified is 5XX all status codes between 500-512 will be exported.
Support for Media Type Ranges e.g. */*
Support for content-type ranges has been added which is a feature supported by OpenAPI 3.0 and WADL. Information related to these ranges will therefore be imported/exported where applicable.
responses:
'200':
description: Successful Response
content:
*/*:
schema:
type: object
properties:
id:
type: number
Improved Support for RAML v1.0 Default Media Types
Previously, if your RAML v1.0 specification file contained a list of media types at root level, our importer only utilized the first/default media type and ignored the rest. However, we now support multiple media types specified at root level. This means that if there is no media type at response level to override root level media type(s), response body content will be loaded for every media type in the root media types list.
Changes to Accept Header In Postman Export
If the Accept header is not found in the imported specification file, then while exporting to Postman 1.0 and 2.0, this header will now be generated automatically from response content information.
How to Disable This Feature?
If you do not wish to receive the changes described above, please upload a Metadata file along with your specification file at the time of importing/transforming your API description file with the ImportMultipleResponses import setting disabled.
The import setting used for disabling this feature has been renamed from DisableMultipleResponses to ImportMultipleResponses. In case you are using the older name in your settings, please update the name as well as its value to avoid any issues.