From 338ff631539abe6db6706e22971620b25d84e8b1 Mon Sep 17 00:00:00 2001 From: cillas Date: Thu, 16 Aug 2018 14:22:18 +0200 Subject: [PATCH] Add swagger.yaml --- docs/reference/swagger.yaml | 882 ++++++++++++++++++++++++++++++++++++ 1 file changed, 882 insertions(+) create mode 100644 docs/reference/swagger.yaml diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml new file mode 100644 index 00000000..26848826 --- /dev/null +++ b/docs/reference/swagger.yaml @@ -0,0 +1,882 @@ +openapi: 3.0.0 +info: + title: Maps API + description: > + # Introduction + + The CARTO Maps API allows you to generate maps based on data hosted in your + CARTO account and apply custom SQL and CartoCSS to the data. The API + generates a XYZ-based URL to fetch Web Mercator projected tiles using web + clients such as Leaflet, Google Maps, or OpenLayers. + + # Authorization + + In order to access Maps API you must provide an API key. The CARTO + Authorization guide explains how these keys are sent (TLDR: _HTTP basic + auth_ or _query string param_ with the API key token). Depending on the + permissions granted to the provided API key, the request will be authorized + or not. + version: '1' + contact: + name: Have you found an error? Github issues + url: 'https://github.com/CartoDB/Windshaft-cartodb/issues' +servers: + - url: 'https://{user}.{domain}/api/v1' + description: Production server (uses live data) + variables: + domain: + default: carto.com + description: 'If on premise, change it to your domain' + user: + default: username + description: Your username +tags: + - name: Anonymous Maps + description: Anonymous Maps allow you to instantiate a map given SQL and CartoCSS + externalDocs: + url: 'https://carto.com/developers/maps-api/guides/anonymous-maps/' + - name: Named Maps + description: Run a single SQL statement + externalDocs: + url: 'https://carto.com/developers/maps-api/guides/named-maps/' + - name: Static Maps + description: Create static images of parts of maps + externalDocs: + url: 'https://carto.com/developers/maps-api/guides/static-maps-API/' +paths: + /map: + post: + summary: Create map + description: | + tags: + - Anonymous Maps + operationId: instantiateAnonymousMap + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MapConfig' + example: + version: 1.3.0 + layers: + - type: mapnik + options: + cartocss_version: 2.1.1 + cartocss: '#layer { polygon-fill: #FFF; }' + sql: select * from european_countries_e + interactivity: + - cartodb_id + - iso3 + responses: + '200': + description: Ok + content: + application/json: + schema: + $ref: '#/components/schemas/AnonymousMapResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: | + curl -X POST -H "Content-Type: application/json" -d '{ \ + "q": "SELECT count(*) FROM cities", \ + "filename": "number_of_cities.json" \ + }' "https://username.carto.com/api/v2/sql" + '/map/{layergroupid}/{z}/{x}/{y}.png': + get: + parameters: + - $ref: '#/components/parameters/layergroupId' + - $ref: '#/components/parameters/z' + - $ref: '#/components/parameters/x' + - $ref: '#/components/parameters/y' + summary: Get tile + description: | + Get a tile + tags: + - Anonymous Maps + operationId: getTile + responses: + '200': + description: Ok + content: + image/png: + schema: + type: string + format: binary + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png + '/map/{layergroupid}/{layers_filter}/{z}/{x}/{y}.png': + get: + parameters: + - $ref: '#/components/parameters/layergroupId' + - $ref: '#/components/parameters/layersFilter' + - $ref: '#/components/parameters/z' + - $ref: '#/components/parameters/x' + - $ref: '#/components/parameters/y' + summary: Get tile - Layer filter + description: | + tags: + - Anonymous Maps + operationId: getTileWithLayerFilter + responses: + '200': + description: Ok + content: + image/png: + schema: + type: string + format: binary + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png + '/map/{layergroupid}/{layer}/{z}/{x}/{y}.torque.json': + get: + parameters: + - $ref: '#/components/parameters/layergroupId' + - $ref: '#/components/parameters/layerIndex' + - $ref: '#/components/parameters/z' + - $ref: '#/components/parameters/x' + - $ref: '#/components/parameters/y' + summary: Get Torque layer + description: | + If the MapConfig had a Torque layer it could be possible to request it + tags: + - Anonymous Maps + operationId: getTorqueLayer + responses: + '200': + description: Ok + content: + application/json: + schema: + type: object + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png + + '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}': + get: + parameters: + - $ref: '#/components/parameters/layergroupId' + - $ref: '#/components/parameters/z' + - $ref: '#/components/parameters/lat' + - $ref: '#/components/parameters/lng' + - $ref: '#/components/parameters/width' + - $ref: '#/components/parameters/height' + - $ref: '#/components/parameters/format' + summary: Zoom + center + description: | + Zoom + center + tags: + - Static Maps + operationId: getStaticZoomCenter + responses: + '200': + description: Ok + content: + image/png: + schema: + type: string + format: binary + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/v1/map/static/center/c01a54877c62831bb51720263f91fb33/4/20/40/500/500.png + + '/map/static/bbox/{layergroupid}/{west},{south},{east},{north}/{width}/{height}.{format}': + get: + parameters: + - $ref: '#/components/parameters/layergroupId' + - $ref: '#/components/parameters/west' + - $ref: '#/components/parameters/south' + - $ref: '#/components/parameters/east' + - $ref: '#/components/parameters/north' + - $ref: '#/components/parameters/width' + - $ref: '#/components/parameters/height' + - $ref: '#/components/parameters/format' + summary: Bounding Box + description: | + Bounding Box in WGS 84 (EPSG:4326), comma separated values + tags: + - Static Maps + operationId: getStaticBoundingBox + responses: + '200': + description: Ok + content: + image/png: + schema: + type: string + format: binary + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/map/static/bbox/c01a54877c62831bb51720263f91fb33/0/0/30/30/500/500.png + '/map/static/named/{name}/{width}/{height}.{format}': + get: + parameters: + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/width' + - $ref: '#/components/parameters/height' + - $ref: '#/components/parameters/format' + summary: Named map + description: | + Named map + tags: + - Static Maps + operationId: getStaticNamedMap + responses: + '200': + description: Ok + content: + image/png: + schema: + type: string + format: binary + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + security: + - ApiKeyHTTPBasicAuth: [] + - ApiKeyQueryParam: [] + x-code-samples: + - lang: Curl + source: > + curl -X GET \ + + https://username.carto.com/api/map/static/named/mynamedmap/500/500.png + +components: + schemas: + MapConfig: + type: object + properties: + version: + type: string + description: Spec version to use for validation. + default: 1.0.0 + extent: + type: string + description: | + The default map extent for the map projection. + **Note:** Currently, only webmercator is supported. + srid: + type: string + description: The spatial reference identifier for the map. + default: 3857 + maxzoom: + type: string + description: >- + The maximum zoom level for your map. A request beyond the defined + maxzoom returns a 404 error. + default: undefined (infinite) + minzoom: + type: string + description: >- + The minimum zoom level for your map. A request beyond the defined + minzoom returns a 404 error. + default: 0 + layers: + type: array + items: + $ref: '#/components/schemas/Layer' + required: + - layers + Layer: + type: object + properties: + type: + $ref: '#/components/schemas/LayerType' + options: + oneOf: + - $ref: '#/components/schemas/LayerOptionsMapnik' + - $ref: '#/components/schemas/LayerOptionsTorque' + - $ref: '#/components/schemas/LayerOptionsHTTP' + - $ref: '#/components/schemas/LayerOptionsPlain' + - $ref: '#/components/schemas/LayerOptionsNamedMap' + description: Sets different options for each layer type. + required: + - type + - options + LayerOptionsMapnik: + type: object + title: Layer options Mapnik + description: > + If you are using Mapnik as a layer resource, the following + configurations are required in your MapConfig file. + properties: + sql: + type: string + description: > + The SQL request to the user database that will fetch the rendered + data. + + + **Tip:** The SQL request should include the following Mapnik layer + configurations: + * ```geom_column``` + * ```interactivity``` + * ```attributes``` + + + **Note:** The SQL request may contain substitutions tokens, such as + ```!bbox!```, ```!pixel_width!``` and ```!pixel_height!```. It is + suggested to define the layergroup ```minzoom``` and ```extent``` + variables to prevent errors. + cartocss: + $ref: '#/components/schemas/CartoCSS' + cartocss_version: + $ref: '#/components/schemas/CartoCSSVersion' + geom_column: + type: string + description: > + The name of the column containing the geometry. + + + *You **must** specify this value as part of the Mapnik layer + SQLconfiguration. + default: the_geom_webmercator + geom_type: + type: string + enum: + - geometry + - raster + description: > + Defines the type of column as either _geometry_ or _raster_. + + + **Note:** ```geom_type``` is not compatible with the Mapnik layer + interactivity option. + default: geometry + raster_band: + type: string + description: > + Defines the raster band (this option is only applicable when the + ```geom_type=raster```. + + + **Note:** If the default, or no value is specified, raster bands are + interpreted as either: + * grayscale (for single bands) + * RGB (for 3 bands) + * RGBA (for 4 bands). + default: 0 + srid: + $ref: '#/components/schemas/Srid' + affected_tables: + $ref: '#/components/schemas/Affected_tables' + interactivity: + type: string + description: > + A string of values that contains the fields rendered inside + grid.json. All the parameters should be exposed as a result of + executing the Mapnik layer SQL query. + + + **Note:** interactivity is not compatible with the Mapnik layer + ```geom_type``` option. For example, you cannot create a layergroup + instance with a raster layer by defining the ```geom_type=raster```. + + *You **must** specify this value as part of the Mapnik layer SQL + configuration. + attributes: + description: > + The id and column values returned by the Mapnik attributes service. + (This option is disabled if no configuration is defined). + + *You **must** specify this value as part of the Mapnik layer SQL + configuration. + type: array + items: + type: object + properties: + id: + type: string + description: The key value used to fetch columns. + columns: + type: string + description: >- + A string of values (columns) returned by the Mapnik attribute + service. + required: + - id + - columns + required: + - sql + - cartocss + - cartocss_version + LayerOptionsTorque: + type: object + title: Layer options Torque + description: > + If you are using Torque as a layer resource, the following + configurations are required in your MapConfig file. For more details + about Torque layers in general, see the Torque API documentation. + properties: + sql: + type: string + description: > + The SQL request to the user database that will fetch the rendered + data. + + + **Tip:** The SQL request should include the following Mapnik layer + configurations: + * geom_column + * interactivity + * attributes + cartocss: + $ref: '#/components/schemas/CartoCSS' + cartocss_version: + $ref: '#/components/schemas/CartoCSSVersion' + step: + type: integer + description: >- + The number of animation steps to render when requesting a torque.png + tile. + default: 0 + geom_column: + type: string + description: > + The name of the column containing the geometry. + + + *You **must** specify this value as part of the Torque layer + SQLconfiguration. + default: the_geom_webmercator + srid: + $ref: '#/components/schemas/Srid' + affected_tables: + $ref: '#/components/schemas/Affected_tables' + attributes: + description: > + The id and column values returned by the Torque attributes service. + (This option is disabled if no configuration is defined). + + *You **must** specify this value as part of the Torque layer SQL + configuration. + type: array + items: + type: object + properties: + id: + type: string + description: The key value used to fetch columns. + columns: + type: string + description: >- + A string of values (columns) returned by the Torque attribute + service. + required: + - id + - columns + required: + - sql + - cartocss + - cartocss_version + LayerOptionsHTTP: + title: Layer options HTTP + type: object + properties: + urlTemplate: + type: string + description: > + URL from where the tile data is retrieved. _URLs must be included in + the configuration whitelist to be valid._ + + + **Note:** It includes + + * ```{z}``` as the zoom level + + * ```{x} ```and ```{y}``` as the tile coordinates + + * Optionally, the subdomain ```{s}``` may be included as part of the + ```urlTemplate``` configuration. Otherwise, you can define the + ```subdomains``` separately, as shown below. + subdomains: + type: string + description: > + A string of values used to retrieve tiles from different + subdomains. The default value is [```a```, ```b```, ```c```] when + ```{s}``` is defined in the urlTemplate configuration. Otherwise, + the default value is ```[ ]```. + + + **Note:** The subdomains value will consistently replace the + ```{s}``` value defined in the ```urlTemplate```. + tms: + type: boolean + description: > + Specifies whether the tile is using Tile Map Service format + + + **Note:** If the value is ```true```, the TMS inverses the Y axis + numbering for tiles. + default: true + tms2: + type: boolean + description: > + Specifies whether the tile is using Tile Map Service format + + + **Note:** If the value is ```true```, the TMS inverses the Y axis + numbering for tiles. + default: false + required: + - urlTemplate + LayerOptionsPlain: + title: Layer options Plain + type: object + properties: + color: + type: string + description: > + Numbers that define the valid colors to include. Valid colors: + + - A string value that includes CSS colors (i.e. ```blue```) or a hex color string (i.e. ```#0000ff```) + + - An integer array of r,g,b values (i.e. ```[255,0,0]```) + + - An integer array of r,g,b,a values (i.e. ```[255,0,0,128]```) + + + + If **only** the ```color``` value is used for a plain layer, this + value is Required. + + + If **both** ```color``` and ```imageUrl``` are defined, only the + color value is used for the plain layer configuration. + default: null + imageUrl: + type: string + description: > + URL from where the image is retrieved + + * If **only** the ```imageUrl``` value is used for a plain layer, + this value is Required. + + * If ```color``` is defined, this ```imageUrl``` value is ignored. + default: null + LayerOptionsNamedMap: + type: object + properties: + name: + type: string + description: 'A string value, the name for the Named Map to use.' + config: + type: object + description: >- + An object, the replacement values for the Named Map’s template + placeholders. + auth_tokens: + type: array + items: + type: string + description: token + description: >- + Strings array, the authorized tokens in case the Named Map has auth + method set to ```token```. + required: + - name + CartoCSS: + type: string + title: cartocss + description: > + Specifies the CartoCSS style to render the tiles. + + + **Note:** The CartoCSS specification is dependent on the layer type. For + details, see mapnik-reference.json. + CartoCSSVersion: + type: string + title: cartocss version + description: > + A string value, specifying the CartoCSS style version of the CartoCSS + attribute. + + + **Note:** The CartoCSS version is specific to the layer type. + Srid: + type: string + description: The spatial reference identifier for the geometry column. + default: 3857 + Affected_tables: + type: string + title: Affected Tables + description: > + A string of values containing the tables that the Mapnik layer SQL + configuration is using. This value is used if there is a problem + guessing what the affected tables are from the SQL configuration (i.e. + when using PL/SQL functions). + LayerType: + title: Layer type + type: string + enum: + - mapnik + - cartodb + - torque + - http + - plain + - named + description: | + A string value that defines the layer type: + * **mapnik** - rasterized tiles + * **cartodb** - an alias for mapnik (for backward compatibility) + * **torque** - render vector tiles in torque format + * **http** - load tiles over HTTP + * **plain** - color or background image url + * **named** - use a Named Map as a layer + AnonymousMapResponse: + type: object + properties: + layergroupid: + type: string + updated_at: + type: string + format: date-time + metadata: + type: object + properties: + layers: + type: array + items: + type: object + properties: + type: + $ref: '#/components/schemas/LayerType' + meta: + type: object + cdn_url: + type: object + properties: + http: + type: string + https: + type: string + securitySchemes: + ApiKeyHTTPBasicAuth: + type: http + scheme: basic + ApiKeyQueryParam: + type: apiKey + in: header + name: api_key + parameters: + layergroupId: + in: path + name: layergroupid + required: true + schema: + type: string + description: The layergroup ID. + z: + in: path + name: z + required: true + schema: + type: integer + minimum: 0 + description: Zoom level. + x: + in: path + name: x + required: true + schema: + type: integer + description: X coordinate. + 'y': + in: path + name: 'y' + required: true + schema: + type: integer + description: Y coordinate. + lng: + in: path + name: lng + required: true + schema: + type: number + format: float + description: The longitude for the center of the map. + lat: + in: path + name: lat + required: true + schema: + type: number + format: float + description: The latitude for the center of the map. + width: + in: path + name: width + required: true + schema: + type: integer + description: Width in pixels for the output image. + height: + in: path + name: height + required: true + schema: + type: integer + description: Height in pixels for the output image. + format: + in: path + name: format + required: true + schema: + type: string + enum: + - png + - jpg + description: Output image format + west: + in: path + name: west + required: true + schema: + type: number + format: float + description: LowerCorner longitude, in decimal degrees (aka most western) in WGS 84 (EPSG:4326) + south: + in: path + name: south + required: true + schema: + type: number + format: float + description: LowerCorner latitude, in decimal degrees (aka most southern) in WGS 84 (EPSG:4326) + east: + in: path + name: east + required: true + schema: + type: number + format: float + description: UpperCorner longitude, in decimal degrees (aka most eastern) in WGS 84 (EPSG:4326) + north: + in: path + name: north + required: true + schema: + type: number + format: float + description: UpperCorner latitude, in decimal degrees (aka most northern) in WGS 84 (EPSG:4326) + name: + in: path + name: name + required: true + schema: + type: string + description: The named map name + + layersFilter: + in: path + name: layers_filter + required: true + schema: + oneOf: + - type: string + title: all + - type: string + title: list of indexes + description: | + Layers to be rendered together. + + Supports 2 format options: + * a comma separated list of layer indexes (0-based). Examples: + + * **0,1,3** - will filter and blend layers with indexes 0, 1 and 3 + * **2** - only one layer + + * **all** will blend all layers in the layergroup + layerIndex: + in: path + name: layer + required: true + schema: + type: number + title: layer index + minimum: 0 + description: 0 based layer index + responses: + NotFound: + description: The specified resource was not found + Unauthorized: + description: Unauthorized. No authentication provided. + Forbidden: + description: Forbidden. The API key does not authorize this request. + BadInput: + description: Request's parameters error