Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue 719 header param table schema doc #287

Merged
merged 4 commits into from
Nov 16, 2023
Merged

Issue 719 header param table schema doc #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
22d948f
Document table-schema and missing header parameter in download options
Nov 14, 2023
34fd042
Refresh api.md
Nov 14, 2023
0c122e0
Detail the result of table-schema endpoint
Nov 16, 2023
02c3174
Refresh api.md
Nov 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 71 additions & 1 deletion api/grist.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,9 +466,10 @@ paths:
schema:
$ref: "#/components/schemas/DocKey"
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A documents's content in Excel form
description: A document's content in Excel form
content:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
schema:
Expand All @@ -492,13 +493,41 @@ paths:
type: string
description: "Name of a table (normalized)."
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's content in CSV form
content:
text/csv:
schema:
type: string
/docs/{docId}/download/table-schema:
get:
operationId: downloadTableSchema
tags:
- docs
summary: "The schema of a table"
description: "The schema follows [frictionlessdata's table-schema standard](https://specs.frictionlessdata.io/table-schema/)."
parameters:
- in: path
name: docId
schema:
$ref: "#/components/schemas/DocKey"
required: true
- in: query
name: tableId
schema:
type: string
description: "Name of a table (normalized)."
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's table-schema in JSON format.
content:
text/json:
schema:
$ref: '#/components/schemas/TableSchemaResult'
/docs/{docId}/tables/{tableId}/data:
get:
operationId: getTableData
Expand Down Expand Up @@ -2087,6 +2116,37 @@ components:
id: 2
pet: dog
popularity: 95
TableSchemaResult:
type: object
required:
- name
- title
- schema
properties:
name:
type: string
description: "The ID (technical name) of the table"
title:
type: string
description: "The human readable name of the table"
path:
type: string
description: "The URL to download the CSV"
example: "https://getgrist.com/o/docs/api/docs/ID/download/csv?tableId=Table1&...."
format:
type: string
enum: ["csv"]
mediatype:
type: string
enum: ["text/csv"]
encoding:
type: string
enum: ["utf-8"]
dialect:
$ref: https://specs.frictionlessdata.io/schemas/csv-dialect.json
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you feel uncomfortable with referencing external references, I can download the JSON and either include the YAML in the document or index as is locally in the repository. (also same remark for schema).

schema:
$ref: https://specs.frictionlessdata.io/schemas/table-schema.json

parameters:
filterQueryParam:
in: query
Expand Down Expand Up @@ -2160,3 +2220,13 @@ components:
schema:
type: boolean
description: "Set to true to include the hidden columns (like \"manualSort\")"
headerQueryParam:
in: query
name: header
schema:
type: string
description: "Format for headers. Labels tend to be more human-friendly while colIds are more normalized."
enum:
- colId
- label
required: false
Loading
Loading