Transform API

The Mashery v3 API supports the Transform API resource, which will convert API definitions from various source formats into Mashery API and/or IO Doc definitions. Current supported source format is the OpenAPI Initiative format, also known as Swagger.

Request

Method URL            
POST v3/transform?sourceFormat=<SrcFmt>&targetFormat=<TgtFmt>&publicDomain=<DomainUri>

 

Query Parameters

Param_Key

Param_Identifier

 Description

Values

Required

sourceFormat

SrcFmt

Defines the type of document that can be provided to the Transform API as raw data to be transformed from. If left empty, the default value that will be used is “swagger2”.

{swagger2}

[optional]

targetFormat

TgtFmt

Defines the type of document that can be provided to the Transform API as raw data to be transformed to. If left empty, the default value that will be used is “masheryapi”.

{masheryapi, iodocsv1}

[optional]

publicDomain

DomainUri

Defines domain name to be used as Mashery context domain for all endpoints that will be associated with the API definition. There is no default value for this query parameter. If left empty, this will result in a 400 Bad Request.

Note: This value has to be whitelisted in Mashery’s system for it to be used as a Mashery context domain.

<Domain Uri>

Yes

Response

Status

Response

200

{

   "document": <converted document>,

   "validationErrors": [],

   "feasibilityErrors": []

}

converted document (json) – Converted API document in the required targetFormat in JSON form.

Validation Errors (array) – If there are some constraint errors encountered during conversion from one format to the other, this list will be populated

Feasibility Errors (array) – This list will be populated if, for some syntactical reason, the source document cannot be converted to the target format.

400

{"errorMessage": "An error occurred during transformation; please review your source document for schematic correctness"}

400

{"errorMessage": "Infeasible transform"}

403

{"errorMessage":"Forbidden"}

500

{"errorMessage":"Internal Server Error"}

Notes

Conventions

  • Status - HTTP status code of response.
  • All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server. 
  • All responses are in JSON format. 
  • All request parameters are mandatory unless explicitly marked as [optional].  

Status Codes 

All status codes are standard HTTP status codes. The following codes are used in this API.

  • 2XX - Success of some kind
  • 4XX - Error occurred in client’s part
  • 5XX - Error occurred in server’s part

Status Code

Description

200

OK

400

Bad request

400

Infeasible Transform. Usually accompanied by an errors[] list, which describes some missing or invalid property in the source document.

403

Forbidden. Usually happens when the user making the call doesn’t have the right permissions for the area.

500

Internal Server Error

503

Service Unavailable

Example Transform API import call:

https://api.mashery.com/v3/rest/transform?sourceFormat=swagger2&targetFormat=masheryapi&publicDomain=<<area name>>.api.mashery.com

Put the Swagger schema in the request body.

Example Transform import response:

{"document":{"name":"CurrencyConverter","version":"1.0.0","endpoints":[{"name":"CurrencyConverter.conversionrate.(fromcurrency).(tocurrency)","outboundRequestTargetPath":"/conversionrate/{fromcurrency}/{tocurrency}","outboundTransportProtocol":"https","publicDomains":[{"address":"tibcodemo.api.mashery.com"}],"requestAuthenticationType":"apiKey","requestPathAlias":"/conversionrate/{fromcurrency}/{tocurrency}","requestProtocol":"rest","supportedHttpMethods":["get"],"systemDomains":[{"address":"app.cloud.tibco.com"}],"trafficManagerDomain":"tibcodemo.api.mashery.com","inboundSslRequired":false}]},"validationErrors":[],"feasibilityErrors":[]}

The "document" part of this response contains the converted schema as a JSON object, which should then be used as the input data to a /services POST call.

Docs Navigation