Web service reference#
The HTTP service is a FastAPI application.
Start it with the server command, as described in the Command line reference.
The service needs the server extra: install collective.html2blocks[server].
The interactive API documentation is available at /docs.
Every response includes the X-Process-Time header, which holds the processing time in seconds.
Endpoints#
Method |
Path |
Request body |
Response |
|---|---|---|---|
|
|
None |
An object with the |
|
|
None |
|
|
|
None |
A list with one object per supported block type. |
|
|
|
A list of blocks. |
|
|
|
A list of blocks. |
|
|
|
An object with the |
|
|
A content item with the |
The content item with the |
GET /blocks#
List the Volto block types the converters can produce.
Each object has the block_type, package, description, enabled, required, tags, providers, options and fallback keys.
enabled is the default state of the block type, and required is true for a block type that can't be disabled.
Each entry of options has the name, type and default keys.
POST /html#
Convert HTML to a list of blocks.
Field |
Type |
Required |
Default |
Description |
|---|---|---|---|---|
|
string |
Yes |
None |
The HTML to convert. |
|
string |
No |
|
The converter to use, |
|
string |
No |
|
The title of the content, for a |
|
object |
No |
|
Enables, disables and configures block types. See The blocks field. |
If converter has any other value, the service responds with status 400.
POST /markdown#
Convert Markdown to a list of blocks.
Field |
Type |
Required |
Default |
Description |
|---|---|---|---|---|
|
string |
Yes |
None |
The Markdown to convert. |
|
string |
No |
|
The converter to use, |
|
string |
No |
|
The title of the content, for a |
|
object |
No |
|
Enables, disables and configures block types. See The blocks field. |
If converter has any other value, the service responds with status 400.
POST /volto#
Convert HTML or Markdown to the structure that Volto uses for a content item.
Field |
Type |
Required |
Default |
Description |
|---|---|---|---|---|
|
string |
Yes |
None |
The HTML or Markdown to convert. The field has this name for both formats. |
|
string |
No |
|
The format of |
|
list of objects |
No |
|
Blocks to place before the converted blocks. |
|
list of objects |
No |
|
Blocks to place after the converted blocks. |
|
object |
No |
|
Enables, disables and configures block types. See The blocks field. |
|
string |
No |
|
The converter to use, |
|
string |
No |
|
The title of the content, for a |
If format has any other value, the service responds with status 422, the validation error status of FastAPI.
If converter has any other value, the service responds with status 400.
With the plate converter, the response has the __somersault__ block as its only block.
POST /slate2plate#
Add the __somersault__ block to a content item with Slate blocks.
The request body is the content item.
Field |
Type |
Required |
Default |
Description |
|---|---|---|---|---|
|
object |
Yes |
None |
The blocks of the content item. |
|
object |
Yes |
None |
The layout of the blocks. |
|
string |
No |
|
The title of the content item, for a |
Other keys are returned unchanged.
The existing blocks stay in the response.
A content item that already has the __somersault__ block comes back unchanged.
If blocks or blocks_layout is missing, the service responds with status 422.
The blocks field#
The keys of blocks are Volto block types, as listed by GET /blocks and in Supported blocks.
true, or an object of options, enables a block type, and false disables it.
Block types left out keep their default state.
{"html": "<pre>ls</pre>", "blocks": {"codeBlock": {"style": "light"}, "slateTable": false}}
For an unknown block type or option, a value of the wrong type, or a block type that can't be disabled, the service responds with status 400.
The detail key of the response says what is wrong.
Example#
Request:
{"html": "# Hello", "format": "markdown"}
The response has the blocks and blocks_layout keys.
The block identifiers are random UUIDs.