API Document

VulcanSQL builds and serves the API documentation automatically, all you have to do is to choose the desired document format.

After VulcanSQL server starts, visit <vulcan-endpoint>/doc to view the document. You can also download the specification from that page.

Make your document better

Although we'll generate all the required fields of API specification for you, you can make your document better by adding more detailed API descriptions:

Set sampler

VulcanSQL has the ability to “guess” the response format by sending a sample query to your warehouse. To enable this feature, you need to set the sample property of each API schema.

For example:

urlPath: /artist/:id
request:
  - fieldName: id
    fieldIn: path
    description: constituent id
    validators:
      - required
sample:
  parameters:
    id: '1'
  profile: duck
profiles:
  - duck

This field has two properties:

Property name	Required	Description
parameters	N	The parameters we should use to send sampling queries.
profile	Y	The profile name we should use to send sampling queries.

Add validators for the requesters

Adding more validators and setting the proper arguments can let your API more stable, and we can also tell users more about your API.

fieldName: age
fieldIn: query
type: number
validators:
  - required
  - name: integer
    args:
      min: 18

Add descriptions about the requests and the responses

You can add descriptions for both requests and responses:

request:
  - fieldName: age
    fieldIn: query
    type: number
    description: Filter the age of artists
    validators:
      - required
      - name: integer
        args:
          min: 18
response:
  - name: ArtistBio
    description: The url to artist's bio
    required: true

info

You can list the response properties partially, we'll merge the result from Sampler