cartodb4/Windshaft-cartodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add swagger.yaml

Browse Source
This commit is contained in:
cillas 2018-08-16 14:22:18 +02:00 committed by GitHub
parent 6e1f66ad94
commit 338ff63153
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 882 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

882
docs/reference/swagger.yaml Normal file
View File

@ -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