cartodb/CartoDB-SQL-API
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Replace markdown file with swagger.yaml in reference section

Browse Source
This commit is contained in:
csubira 2018-05-24 12:46:22 +02:00
parent 395e7a0c1f
commit b79fc0589b
2 changed files with 523 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
docs/reference/01-making-calls.md
View File

@ -1,201 +0,0 @@
## Making Calls to the SQL API
CARTO is based on the rock solid PostgreSQL database. All of your tables reside in a single database, which means you can perform complex queries joining tables, or carrying out geospatial operations. The best place to learn about PostgreSQL's SQL language is the [official documentation](http://www.postgresql.org/docs/9.1/static/).
CARTO is also based on PostGIS, so you can view the [official PostGIS reference](http://postgis.refractions.net/docs/) to know what functionality we support in terms of geospatial operations. All of our tables include a column called *the_geom,* which is a geometry field that indexes geometries in the EPSG:4326 (WGS 1984) coordinate system. All tables also have an automatically generated and updated column called *the_geom_webmercator*. We use the column internally to quickly create tiles for maps.
### URL Endpoints
All SQL API requests to your CARTO account should follow this general pattern:
##### SQL Query Example
```bash
https://{username}.carto.com/api/v2/sql?q={SQL statement}
```
If you encounter errors, double-check that you are using the correct account name, and that your SQL statement is valid. A simple example of this pattern is conducting a count of all the records in your table:
##### Count Example
```bash
https://{username}.carto.com/api/v2/sql?q=SELECT count(*) FROM {table_name}
```
##### Result
```javascript
{
time: 0.007,
total_rows: 1,
rows: [
{
count: 4994
}
]
}
```
Finally, remember that in order to use the SQL API, either your table must be public, or you must be [authenticated](http://docs.carto.com/carto-engine/sql-api/authentication/#authentication) using API Keys.
### POST and GET
The CARTO SQL API is setup to handle both GET and POST requests. You can test the GET method directly in your browser. Below is an example of a jQuery SQL API request to CARTO:
#### jQuery
##### Call
```javascript
$.getJSON('https://{username}.carto.com/api/v2/sql/?q='+sql_statement, function(data) {
$.each(data.rows, function(key, val) {
// do something!
});
});
```
By default, GET requests work from anywhere. In CARTO, POST requests work from any website as well. We achieve this by hosting a cross-domain policy file at the root of all of our servers. This allows you the greatest level of flexibility when developing your application.
### Response Formats
The SQL API accepts many output formats that can be useful to export data, such as:
- GPKG
- CSV
- SHP
- SVG
- KML
- SpatiaLite
- GeoJSON
The most common response format used is JSON. For example, if you are building a web-application, the lightweight JSON format allows you to quickly integrate data from the SQL API. This section focuses on the call and response functions for generating the JSON output format.
#### JSON
##### Call
```bash
https://{username}.carto.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
```
##### Result
```javascript
{
time: 0.006,
total_rows: 1,
rows: [
{
year: " 2011",
month: 10,
day: "11",
the_geom: "0101000020E610...",
cartodb_id: 1,
the_geom_webmercator: "0101000020110F000..."
}
]
}
```
Alternatively, you can use the [GeoJSON specification](http://www.geojson.org/geojson-spec.html) to return data from the API. To do so, simply supply the `format` parameter as GeoJSON:
#### GeoJSON
##### Call
```bash
https://{username}.carto.com/api/v2/sql?format=GeoJSON&q=SELECT * FROM {table_name} LIMIT 1
```
##### Result
```javascript
{
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {
year: " 2011",
month: 10,
day: "11",
cartodb_id: 1
},
geometry: {
type: "Point",
coordinates: [
-97.335,
35.498
]
}
}
]
}
```
### Output Filename
To customize the output filename, add the `filename` parameter to your URL:
##### Call
```bash
https://{username}.carto.com/api/v2/sql?filename={custom_filename}&q=SELECT * FROM {table_name} LIMIT 1
```
### Getting Table Information
Currently, there is no public method to access your table schemas. The simplest way to retrieve table structure is to access the first row of the data,
##### Call
```bash
https://{username}.carto.com/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
```
### Response Errors
To help you debug your SQL queries, the CARTO SQL API returns the full error provided by PostgreSQL, as part of the JSON response. Error responses appear in the following format,
##### Result
```javascript
{
error: [
"syntax error at or near "LIMIT""
]
}
```
You can use these errors to help understand your SQL. If you encounter errors executing SQL, either through CARTO Builder, or through the SQL API, it is suggested to Google search the error for independent troubleshooting.
### Write Data to your CARTO Account
When writing data to your CARTO account, you are executing SQL queries to manage data in a table. Performing inserts or updates on your data is achieved by using your [API Key]({{ site.sqlapi_docs }}/guides/authentication/). Simply supply a well-formatted SQL [INSERT](http://www.postgresql.org/docs/9.1/static/sql-insert.html) or [UPDATE](http://www.postgresql.org/docs/9.1/static/sql-update.html) statement for your table, along with the api_key parameter for your account.
**Tip:** All requests should be private, as anyone with your API Key will be able to modify your tables.
A well-formatted SQL insert statement means that all of the columns that you want to insert to your data already exist in your table, and all the values for those columns are the correct type (quoted string, unquoted string for geoms and dates, or numbers).
#### Insert
##### Call
```bash
https://{username}.carto.com/api/v2/sql?q=INSERT INTO test_table (column_name, column_name_2, the_geom) VALUES ('this is a string', 11, ST_SetSRID(ST_Point(-110, 43),4326))&api_key={api_key}
```
Updates are just as simple. The following example displays how to update a row based on the value of the `cartodb_id` column.
#### Update
##### Call
```bash
https://{username}.carto.com/api/v2/sql?q=UPDATE test_table SET column_name = 'my new string value' WHERE cartodb_id = 1 &api_key={api_key}
```

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

@ -0,0 +1,523 @@
openapi: 3.0.0
info:
title: SQL API
description: >
# Introduction
CARTO’s SQL API allows you to interact with your tables and data inside
CARTO, as if you were running SQL statements against a normal database.
You can execute single SQL statements or even a batch of long-running ones.
Refer to the SQL API guide to learn more.
# Authorization
In order to access SQL 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: 0.0.1
contact:
name: Have you found an error? Github issues
url: 'https://github.com/CartoDB/CartoDB-SQL-API/issues'
servers:
- url: 'https://{user}.{domain}/api/v2/'
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: Single SQL Statement
description: Run a single SQL statement
externalDocs:
url: 'http://doc.carto.com/pet-operations.htm'
- name: Batch Queries
description: >-
A Batch Queries Job enables you to request statements with long-running
CPU processing times
externalDocs:
url: 'http://doc.carto.com/pet-operations.htm'
paths:
/sql:
get:
summary: Runs a single SQL statement
description: |
Runs a single SQL statement:
- SELECT, INSERT, UPDATE, DELETE,
- CREATE TABLE, ALTER TABLE, DROP TABLE
- CREATE INDEX
tags:
- Single SQL Statement
operationId: getSQLStatement
parameters:
- in: query
name: q
description: SQL statement
schema:
$ref: '#/components/schemas/SQLStatementString'
required: true
- in: query
name: filename
description: Output filename
schema:
type: string
required: false
- in: query
name: format
schema:
$ref: '#/components/schemas/OutputFormat'
required: false
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/StatementResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
security:
- ApiKeyHTTPBasicAuth: []
- ApiKeyQueryParam: []
x-code-samples:
- lang: Curl
source: |
curl -X GET \
https://username.carto.com/api/v2/sql?q=SELECT count(*) FROM cities
post:
summary: Runs a single SQL statement.
description: >
Runs a single SQL statement:
- SELECT, INSERT, UPDATE, DELETE,
- CREATE TABLE, ALTER TABLE, DROP TABLE
- CREATE INDEX
Offers the same functionality as the GET endpoint. This version may come
handy when dealing with complex/long statments.
tags:
- Single SQL Statement
operationId: postSQLStatement
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
q:
$ref: '#/components/schemas/SQLStatementString'
filename:
type: string
description: Output filename
format:
$ref: '#/components/schemas/OutputFormat'
required:
- q
example:
q: SELECT count(*) FROM cities
filename: number_of_cities.json
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/StatementResult'
'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 '{ \
"query": "SELECT count(*) FROM cities", \
"filename": "number_of_cities.json" \
}' "https://username.carto.com/api/v2/sql"
/sql/job:
post:
summary: Create a Job
description: Creates a Batch Queries Job
tags:
- Batch Queries
operationId: createJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobQueryField'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
example:
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
user: username
status: pending
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
created_at: '2017-12-15T07:36:25Z'
updated_at: '2017-12-15T07:36:25Z'
'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 '{ \
"query": "UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'", \
}' "https://username.carto.com/api/v2/sql/job"
'/sql/job/{job_id}':
parameters:
- $ref: '#/components/parameters/jobId'
get:
summary: Get a Job
description: Returns a Batch Queries Job based on it's ID.
tags:
- Batch Queries
operationId: getJob
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
example:
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
user: username
status: pending
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
created_at: '2017-12-15T07:36:25Z'
updated_at: '2017-12-15T07:36:25Z'
'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/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
put:
summary: Update a Job
description: |
Updates the query of a Batch Queries Job.
**Notice:** Only the _query_ property can be updated
tags:
- Batch Queries
operationId: updateJob
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobQueryField'
example:
q: UPDATE nasdaq SET price = '$999.00' WHERE company = 'CARTO'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
example:
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
user: username
status: pending
query: UPDATE nasdaq SET price = '999.00' WHERE company = 'CARTO'
created_at: '2017-12-15T07:36:25Z'
updated_at: '2017-12-16T12:52:13Z'
'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 PUT -H "Content-Type: application/json" -d '{ \
"query": "UPDATE nasdaq SET price = '$999.00' WHERE company = 'CARTO'", \
}'
"https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014"
delete:
summary: Cancel a Job
description: >
Canceles a Batch Queries Job based on it's ID. The Job doesn't get
deleted, just it's status is set as _canceled_.
Only jobs whose status are _pending_ or _running_ can be canceled.
* **pending**: the job will never be executed
* **running**: the job will be terminated immediately
tags:
- Batch Queries
operationId: cancelJob
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
example:
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
user: username
status: canceled
query: UPDATE nasdaq SET price = '999.00' WHERE company = 'CARTO'
created_at: '2017-12-15T07:36:25Z'
updated_at: '2017-12-16T12:52:13Z'
'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 DELETE \
https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
components:
schemas:
StatementResult:
type: object
properties:
time:
type: number
format: float
description: time in seconds it has taken to run the statement
total_rows:
type: number
format: integer
description: number of rows returned
rows:
type: array
items:
type: object
description: the structure/data depends on the statement
example:
time: 0.007
total_rows: 1
rows:
- count: 4994
Job:
allOf:
- $ref: '#/components/schemas/SQLGeneralStatment'
- type: object
properties:
job_id:
type: string
format: uuid
description: a Job's universally unique identifier (uuid).
user:
type: string
description: 'user identifier, as displayed by the username.'
status:
$ref: '#/components/schemas/JobStatus'
failed_reason:
description: 'displays the database error message, if something went wrong.'
type: string
- $ref: '#/components/schemas/Timestamps'
example:
job_id: de305d54-75b4-431b-adb2-eb6b9e546014
user: username
status: pending
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
created_at: '2017-12-15T07:36:25Z'
updated_at: '2017-12-15T07:36:25Z'
OutputFormat:
title: Output format
type: string
enum:
- GPKG
- CSV
- SHP
- SVG
- KML
- SpatiaLite
- GeoJSON
description: Output format
JobStatus:
title: Job status
type: string
enum:
- pending
- running
- done
- failed
- canceled
- unknown
description: displays the result of the long-running statement
SQLStatementString:
title: SQL statement
type: string
SQLSingleStatement:
type: object
properties:
query:
$ref: '#/components/schemas/SQLStatementString'
required:
- query
CreateJobQueryField:
type: object
properties:
query:
oneOf:
- $ref: '#/components/schemas/SQLStatementString'
- $ref: '#/components/schemas/ArrayOfSQLStatements'
- $ref: '#/components/schemas/CreateJobQueryFieldWithFallbacks'
description: long-running SQL statement(s).
required:
- query
example:
query: UPDATE nasdaq SET price = '$101.00' WHERE company = 'CARTO'
ArrayOfSQLStatements:
title: Array of SQL statements
type: array
items:
$ref: '#/components/schemas/SQLStatementString'
CreateJobQueryFieldWithFallbacks:
title: Array of SQL statements with Fallbacks
allOf:
- $ref: '#/components/schemas/Fallbacks'
- type: object
properties:
query:
type: array
items:
allOf:
- type: object
properties:
query:
$ref: '#/components/schemas/SQLStatementString'
- $ref: '#/components/schemas/Fallbacks'
required:
- query
SQLMultipleStatements:
type: array
items:
$ref: '#/components/schemas/StatementAndStatus'
SQLMultipleStatementsWithFallbacks:
allOf:
- type: object
properties:
query:
type: array
items:
$ref: '#/components/schemas/StatementAndStatusAndFallbacks'
- $ref: '#/components/schemas/Fallbacks'
StatementAndStatus:
title: SQL statement and status
type: object
properties:
query:
$ref: '#/components/schemas/SQLStatementString'
status:
$ref: '#/components/schemas/JobStatus'
StatementAndStatusAndFallbacks:
allOf:
- $ref: '#/components/schemas/StatementAndStatus'
- $ref: '#/components/schemas/Fallbacks'
Fallbacks:
type: object
properties:
onsuccess:
$ref: '#/components/schemas/SQLStatementString'
onerror:
$ref: '#/components/schemas/SQLStatementString'
SQLGeneralStatment:
type: object
properties:
query:
oneOf:
- $ref: '#/components/schemas/SQLStatementString'
- $ref: '#/components/schemas/SQLMultipleStatements'
- $ref: '#/components/schemas/SQLMultipleStatementsWithFallbacks'
description: long-running SQL statement(s).
JobQueryField:
type: object
properties:
query:
oneOf:
- $ref: '#/components/schemas/SQLStatementString'
- $ref: '#/components/schemas/SQLMultipleStatements'
Timestamps:
type: object
properties:
created_at:
type: string
format: date-time
description: the date and time when the job schema was created
updated_at:
type: string
format: date-time
description: >-
the date and time of when the job schema was last updated, or
modified.
securitySchemes:
ApiKeyHTTPBasicAuth:
type: http
scheme: basic
ApiKeyQueryParam:
type: apiKey
in: header
name: api_key
parameters:
jobId:
in: path
name: job_id
required: true
schema:
type: string
format: uuid
description: the job universally unique identifier (uuid).
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