archive/bramw_baserow
1
0
Fork 0
mirror of https://gitlab.com/bramw/baserow.git synced 2025-05-12 04:11:49 +00:00
Code Issues Projects Releases Wiki Activity

Add Baserow docs for batch row endpoints

Browse source
This commit is contained in:
Petr Stribny 2022-06-13 07:37:07 +00:00
parent 86867fb88f
commit 797ded7589
9 changed files with 439 additions and 100 deletions

7
web-frontend/locales/en.json
View file

@ -230,13 +230,18 @@
"listRows": "List rows",
"getRow": "Get row",
"createRow": "Create row",
"createRows": "Create rows",
"updateRow": "Update row",
"updateRows": "Update rows",
"moveRow": "Move row",
"deleteRow": "Delete row",
"deleteRows": "Delete rows",
"queryParameters": "Query parameters",
"pathParameters": "Path parameters",
"requestBodySchema": "Request body schema",
"userFieldNamesDescription": "When any value is provided for the `user_field_names` GET param then field names returned by this endpoint will be the actual names of the fields.\n\n If the `user_field_names` GET param is not provided, then all returned field names will be `field_` followed by the id of the field. For example `field_1` refers to the field with an id of `1`."
"userFieldNamesDescription": "When any value is provided for the `user_field_names` GET param then field names returned by this endpoint will be the actual names of the fields.\n\n If the `user_field_names` GET param is not provided, then all returned field names will be `field_` followed by the id of the field. For example `field_1` refers to the field with an id of `1`.",
"singleRow": "Single",
"batchRows": "Batch"
},
"exporterType": {
"csv": "Export to CSV"

14
web-frontend/modules/core/assets/scss/components/api_docs.scss
View file

@ -131,3 +131,17 @@
.api-docs__content {
color: $color-primary-900;
}
.api-docs__heading-wrapper {
display: flex;
justify-content: space-between;
align-items: baseline;
@media screen and (max-width: $api-docs-breakpoint) {
display: block;
}
}
.api-docs__endpoint-type {
width: 100px;
}

8
web-frontend/modules/core/assets/scss/components/api_docs/parameters.scss
View file

@ -31,6 +31,10 @@
margin: 0 20px 20px 0;
}
.api-docs__parameter-name--parent {
margin: 0 20px 0 0;
}
.api-docs__parameter-visible-name {
color: $color-neutral-700;
margin-left: 4px;
@ -62,3 +66,7 @@
margin-top: 8px;
line-height: 140%;
}
.api-docs__parameter-content--parent {
margin-left: 20px;
}

68
web-frontend/modules/database/components/docs/APIDocsParentParameter.vue Normal file
View file

@ -0,0 +1,68 @@
<template>
<div>
<li>
<div class="api-docs__parameter">
<div class="api-docs__parameter-name">
<div>
{{ userFieldNames ? visibleName : name }}
<span
v-if="userFieldNames || visibleName !== null"
class="api-docs__parameter-visible-name"
>{{ userFieldNames ? name : visibleName }}</span
>
</div>
<div v-if="optional" class="api-docs__parameter-optional">
{{ $t('apiDocsParameter.optional') }}
</div>
</div>
<div class="api-docs__parameter-description">
<code class="api-docs__code">{{ type }}</code>
<div v-if="standard !== ''" class="api-docs__parameter-default">
{{ $t('apiDocsParameter.defaultValue', { value: standard }) }}
</div>
</div>
</div>
</li>
<div
class="api-docs__parameter-content api-docs__parameter-content--parent"
>
<slot></slot>
</div>
</div>
</template>
<script>
export default {
name: 'APIDocsParameter',
props: {
name: {
type: String,
required: true,
},
visibleName: {
type: String,
required: false,
default: null,
},
optional: {
type: Boolean,
required: false,
default: false,
},
type: {
type: String,
required: true,
},
standard: {
type: String,
required: false,
default: '',
},
userFieldNames: {
type: Boolean,
required: false,
default: false,
},
},
}
</script>

153
web-frontend/modules/database/components/docs/sections/APIDocsTableCreateRow.vue
View file

@ -1,48 +1,103 @@
<template>
<div class="api-docs__item">
<div class="api-docs__left">
<h3
:id="'section-table-' + table.id + '-create'"
class="api-docs__heading-3"
>
{{ $t('apiDocs.createRow') }}
</h3>
<p class="api-docs__content">
<div class="api-docs__heading-wrapper">
<h3
:id="'section-table-' + table.id + '-create'"
class="api-docs__heading-3"
>
<span v-if="batchMode === false">
{{ $t('apiDocs.createRow') }}
</span>
<span v-else>
{{ $t('apiDocs.createRows') }}
</span>
</h3>
<div class="api-docs__endpoint-type">
<Checkbox v-model="batchMode">batch mode</Checkbox>
</div>
</div>
<p v-if="batchMode === false" class="api-docs__content">
{{ $t('apiDocsTableCreateRow.description', table) }}
</p>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.queryParameters') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
<APIDocsParameter :optional="true" name="before" type="integer">
{{ $t('apiDocsTableCreateRow.before') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
<p v-else class="api-docs__content">
{{ $t('apiDocsTableCreateRows.description', table) }}
</p>
<div v-if="batchMode === false">
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.queryParameters') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
<APIDocsParameter :optional="true" name="before" type="integer">
{{ $t('apiDocsTableCreateRow.before') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
</div>
<div v-else>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.queryParameters') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
<APIDocsParameter :optional="true" name="before" type="integer">
{{ $t('apiDocsTableCreateRows.before') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters api-docs__parameters--parent">
<APIDocsParentParameter name="items" :optional="false" type="array">
<ul class="api-docs__parameters">
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
</APIDocsParentParameter>
</ul>
</div>
</div>
<div class="api-docs__right">
<div v-if="batchMode === false" class="api-docs__right">
<APIDocsExample
:value="value"
type="POST"
@ -53,17 +108,30 @@
@input="$emit('input', $event)"
></APIDocsExample>
</div>
<div v-else class="api-docs__right">
<APIDocsExample
:value="value"
type="POST"
:url="getListUrl(table, true, true)"
:request="getBatchRequestExample(table)"
:response="getBatchResponseItem(table)"
:mapping="getFieldMapping(table)"
@input="$emit('input', $event)"
></APIDocsExample>
</div>
</div>
</template>
<script>
import APIDocsExample from '@baserow/modules/database/components/docs/APIDocsExample'
import APIDocsParameter from '@baserow/modules/database/components/docs/APIDocsParameter'
import APIDocsParentParameter from '@baserow/modules/database/components/docs/APIDocsParentParameter'
export default {
name: 'APIDocsTableCreateRow',
components: {
APIDocsParameter,
APIDocsParentParameter,
APIDocsExample,
},
props: {
@ -76,8 +144,15 @@ export default {
userFieldNames: { type: Boolean, required: true },
getListUrl: { type: Function, required: true },
getResponseItem: { type: Function, required: true },
getBatchRequestExample: { type: Function, required: true },
getBatchResponseItem: { type: Function, required: true },
getFieldMapping: { type: Function, required: true },
getRequestExample: { type: Function, required: true },
},
data() {
return {
batchMode: false,
}
},
}
</script>

74
web-frontend/modules/database/components/docs/sections/APIDocsTableDeleteRow.vue
View file

@ -1,23 +1,51 @@
<template>
<div class="api-docs__item">
<div class="api-docs__left">
<h3
:id="'section-table-' + table.id + '-delete'"
class="api-docs__heading-3"
>
{{ $t('apiDocs.deleteRow') }}
</h3>
<p class="api-docs__content">
<div class="api-docs__heading-wrapper">
<h3
:id="'section-table-' + table.id + '-delete'"
class="api-docs__heading-3"
>
<span v-if="batchMode === false">
{{ $t('apiDocs.deleteRow') }}
</span>
<span v-else>
{{ $t('apiDocs.deleteRows') }}
</span>
</h3>
<div class="api-docs__endpoint-type">
<Checkbox v-model="batchMode">batch mode</Checkbox>
</div>
</div>
<p v-if="batchMode === false" class="api-docs__content">
{{ $t('apiDocsTableDeleteRow.description', table) }}
</p>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.pathParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="row_id" type="integer">
{{ $t('apiDocsTableDeleteRow.rowId') }}
</APIDocsParameter>
</ul>
<p v-else class="api-docs__content">
{{ $t('apiDocsTableDeleteRows.description', table) }}
</p>
<div v-if="batchMode === false">
<h4 class="api-docs__heading-4">{{ $t('apiDocs.pathParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="row_id" type="integer">
{{ $t('apiDocsTableDeleteRow.rowId') }}
</APIDocsParameter>
</ul>
</div>
<div v-else>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="items" :optional="false" type="array">
{{ $t('apiDocsTableDeleteRows.items') }}
</APIDocsParameter>
</ul>
</div>
</div>
<div class="api-docs__right">
<div v-if="batchMode === false" class="api-docs__right">
<APIDocsExample
:value="value"
type="DELETE"
@ -26,6 +54,17 @@
@input="$emit('input', $event)"
></APIDocsExample>
</div>
<div v-else class="api-docs__right">
<APIDocsExample
:value="value"
type="POST"
:url="getDeleteListUrl(table, false)"
:request="getBatchDeleteRequestExample(table)"
:include-user-fields-checkbox="false"
@input="$emit('input', $event)"
>
</APIDocsExample>
</div>
</div>
</template>
@ -46,6 +85,13 @@ export default {
},
table: { type: Object, required: true },
getItemUrl: { type: Function, required: true },
getDeleteListUrl: { type: Function, required: true },
getBatchDeleteRequestExample: { type: Function, required: true },
},
data() {
return {
batchMode: false,
}
},
}
</script>

156
web-frontend/modules/database/components/docs/sections/APIDocsTableUpdateRow.vue
View file

@ -1,50 +1,102 @@
<template>
<div class="api-docs__item">
<div class="api-docs__left">
<h3
:id="'section-table-' + table.id + '-update'"
class="api-docs__heading-3"
>
{{ $t('apiDocs.updateRow') }}
</h3>
<p class="api-docs__content">
<div class="api-docs__heading-wrapper">
<h3
:id="'section-table-' + table.id + '-update'"
class="api-docs__heading-3"
>
<span v-if="batchMode === false">
{{ $t('apiDocs.updateRow') }}
</span>
<span v-else>
{{ $t('apiDocs.updateRows') }}
</span>
</h3>
<div class="api-docs__endpoint-type">
<Checkbox v-model="batchMode">batch mode</Checkbox>
</div>
</div>
<p v-if="batchMode === false" class="api-docs__content">
{{ $t('apiDocsTableUpdateRow.description', table) }}
</p>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.pathParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="row_id" type="integer">
{{ $t('apiDocsTableUpdateRow.rowId') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.queryParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
<APIDocsParameter :optional="true" name="before" type="integer">
{{ $t('apiDocsTableUpdateRow.before') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.requestBodySchema') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
<p v-else class="api-docs__content">
{{ $t('apiDocsTableUpdateRows.description', table) }}
</p>
<div v-if="batchMode === false">
<h4 class="api-docs__heading-4">{{ $t('apiDocs.pathParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="row_id" type="integer">
{{ $t('apiDocsTableUpdateRow.rowId') }}
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.queryParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters">
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
</div>
<div v-else>
<h4 class="api-docs__heading-4">{{ $t('apiDocs.queryParameters') }}</h4>
<ul class="api-docs__parameters">
<APIDocsParameter name="user_field_names" :optional="true" type="any">
<MarkdownIt
class="api-docs__content"
:content="$t('apiDocs.userFieldNamesDescription')"
/>
</APIDocsParameter>
</ul>
<h4 class="api-docs__heading-4">
{{ $t('apiDocs.requestBodySchema') }}
</h4>
<ul class="api-docs__parameters api-docs__parameters-parent">
<APIDocsParentParameter name="items" :optional="false" type="array">
<ul class="api-docs__parameters">
<APIDocsParameter name="id" type="integer">
{{ $t('apiDocsTableUpdateRows.id') }}
</APIDocsParameter>
<APIDocsParameter
v-for="field in withoutReadOnly[table.id]"
:key="field.id"
:name="'field_' + field.id"
:visible-name="field.name"
:optional="true"
:type="field._.type"
:user-field-names="userFieldNames"
>
<!-- eslint-disable-next-line vue/no-v-html -->
<div v-html="field._.description"></div>
</APIDocsParameter>
</ul>
</APIDocsParentParameter>
</ul>
</div>
</div>
<div class="api-docs__right">
<div v-if="batchMode === false" class="api-docs__right">
<APIDocsExample
:value="value"
type="PATCH"
@ -55,17 +107,30 @@
@input="$emit('input', $event)"
></APIDocsExample>
</div>
<div v-else class="api-docs__right">
<APIDocsExample
:value="value"
type="PATCH"
:url="getListUrl(table, true, true)"
:request="getBatchRequestExample(table)"
:response="getBatchResponseItem(table)"
:mapping="getFieldMapping(table)"
@input="$emit('input', $event)"
></APIDocsExample>
</div>
</div>
</template>
<script>
import APIDocsExample from '@baserow/modules/database/components/docs/APIDocsExample'
import APIDocsParameter from '@baserow/modules/database/components/docs/APIDocsParameter'
import APIDocsParentParameter from '@baserow/modules/database/components/docs/APIDocsParentParameter'
export default {
name: 'APIDocsTableUpdateRow',
components: {
APIDocsParameter,
APIDocsParentParameter,
APIDocsExample,
},
props: {
@ -77,10 +142,17 @@ export default {
withoutReadOnly: { type: Object, required: true },
userFieldNames: { type: Boolean, required: true },
getItemUrl: { type: Function, required: true },
getListUrl: { type: Function, required: true },
getRequestExample: { type: Function, required: true },
getResponseItem: { type: Function, required: true },
getBatchRequestExample: { type: Function, required: true },
getBatchResponseItem: { type: Function, required: true },
getFieldMapping: { type: Function, required: true },
},
methods: {},
data() {
return {
batchMode: false,
}
},
}
</script>

12
web-frontend/modules/database/locales/en.json
View file

@ -162,6 +162,10 @@
"description": "Deletes an existing {name} row.",
"rowId": "The unique identifier of the row that needs to be deleted."
},
"apiDocsTableDeleteRows": {
"description": "Deletes existing {name} rows.",
"items": "An array of row ids that should be deleted."
},
"apiDocsTableMoveRow": {
"description": "Moves an existing {name} row before another row. If no `before_id` is provided, then the row will be moved to the end of the table.",
"rowId": "Moves the row related to the value.",
@ -172,10 +176,18 @@
"rowId": "The unique identifier of the row that needs to be updated.",
"before": "If provided then the newly created row will be positioned before the row with the provided id."
},
"apiDocsTableUpdateRows": {
"description": "Updates existing {name} rows.",
"id": "The row id."
},
"apiDocsTableCreateRow": {
"description": "Create a new {name} row.",
"before": "If provided then the newly created row will be positioned before the row with the provided id."
},
"apiDocsTableCreateRows": {
"description": "Create new {name} rows.",
"before": "If provided then the newly created rows will be positioned before the row with the provided id."
},
"apiDocsAuth": {
"description": "Baserow uses a simple token based authentication. You need to generate at least one API token in your {settingsLink} to use the endpoints described below. It is possible to give create, read, update and delete permissions up until table level per token. You can authenticate to the API by providing your API token in the HTTP authorization bearer token header. All API requests must be authenticated and made over HTTPS.",
"settingsLink": "settings"

47
web-frontend/modules/database/pages/APIDocsDatabase.vue
View file

@ -79,6 +79,8 @@
:user-field-names="exampleData.userFieldNames"
:get-list-url="getListURL"
:get-request-example="getRequestExample"
:get-batch-request-example="getBatchRequestExample"
:get-batch-response-item="getBatchResponseItems"
:get-response-item="getResponseItem"
:get-field-mapping="getFieldMapping"
/>
@ -88,7 +90,10 @@
:without-read-only="withoutReadOnly"
:user-field-names="exampleData.userFieldNames"
:get-item-url="getItemURL"
:get-list-url="getListURL"
:get-request-example="getRequestExample"
:get-batch-request-example="getBatchRequestExample"
:get-batch-response-item="getBatchResponseItems"
:get-response-item="getResponseItem"
:get-field-mapping="getFieldMapping"
/>
@ -104,6 +109,8 @@
v-model="exampleData"
:table="table"
:get-item-url="getItemURL"
:get-delete-list-url="getDeleteListURL"
:get-batch-delete-request-example="getBatchDeleteRequestExample"
/>
</div>
<APIDocsFilters />
@ -279,7 +286,7 @@ export default {
/**
* Generates an example request object based on the available fields of the table.
*/
getRequestExample(table, response = false) {
getRequestExample(table, response = false, includeId = false) {
const item = {}
// In case we are creating a sample response
@ -293,6 +300,10 @@ export default {
)
}
if (includeId) {
item.id = 0
}
fieldsToLoopOver.forEach((field) => {
const example = response
? field._.responseExample
@ -305,6 +316,22 @@ export default {
})
return item
},
/**
* Generates an example request object when providing multiple items.
*/
getBatchRequestExample(table, response = false) {
return {
items: [this.getRequestExample(table, response, true)],
}
},
/**
* Generates an example request object for deleting multiple items.
*/
getBatchDeleteRequestExample(table, response = false) {
return {
items: [0],
}
},
/**
* Generates an example response object based on the available fields of the table.
*/
@ -313,7 +340,14 @@ export default {
Object.assign(item, this.getRequestExample(table, true))
return item
},
/**
* Generates an example response object when multiple items are returned.
*/
getBatchResponseItems(table) {
return {
items: [this.getResponseItem(table)],
}
},
/**
* Returns the mapping of the field id as key and the field name as value.
*/
@ -328,10 +362,15 @@ export default {
})
return mapping
},
getListURL(table, addUserFieldParam) {
getListURL(table, addUserFieldParam, batch = false) {
return `${this.$env.PUBLIC_BACKEND_URL}/api/database/rows/table/${
table.id
}/${addUserFieldParam ? this.userFieldNamesParam : ''}`
}/${batch ? 'batch/' : ''}${
addUserFieldParam ? this.userFieldNamesParam : ''
}`
},
getDeleteListURL(table) {
return `${this.$env.PUBLIC_BACKEND_URL}/api/database/rows/table/${table.id}/batch-delete/`
},
getItemURL(table, addUserFieldParam) {
return (