Levels of request parameter specification

[trin4ik]

Bruno is a convenient and simple API testing/documentation tool. However, different tasks require different levels of query specification. I propose to discuss possible development of Bruno in the direction of query parameter specification.

• Level 1. Owner needs to tests its own API.
• Level 2. Team needs to tests and document its own API for integration between front/back developers.
• Level 3. Team needs to document the API for external developers.

Level 1

Bruno was designed for this task. Bru provides a simple syntax for testing own API.

post {
  url: https://api.textlocal.in/send
}

body {
  {
    "apiKey": "secret",
    "numbers": "9988776655",
    "message": "Woof! lets play with some apis",
  }
}

headers {
  content-type: application/json
  Authorization: Bearer topsecret
}

docs {
  ## Send numbers with message
}

Changelog

• v0.24: Added docs block to describe requests.

Todo

nothing here

Level 2

For communication within the team, the body of the request is not enough, each parameter of the request needs to be typed and described if possible.

Important! Bruno does not aim to impose its specifications on developers. Bruno offers a simple way to interact. More often than not, these blocks will be generated by frameworks automatically.

I propose the following structure of an additional block in Bru for parameter specification:

param:apiKey {
  required: true
  type: string
  validators: {
    length: 32
    regexp: /^[a-f0-9]{32}$/
    md5
  }
  title: API Key
  description: {
    Get API key in your [profile](https://api.textlocal.in/profile/apikeys)
  }
}

All block parameters are optional.

• required -- mark param as required
• type -- type of param. Its only string param, its may be string, String, String:Text etc. It is important to remember that in Bruno this is only required for display in the application.
• validators -- subtypes, like are tags. Helps developers understand what the api wants them to do
• title -- Param titile
• description -- Param markdown description

This could end up looking very visible within the team. For example as it looks in readme.io:
https://developers.baremetrics.com/reference/create-customer

body params looks great, has required flags, descriptions and types

Changelog

nothing here

Todo

• decide on a syntax
• decide on the parameters of the block (required, type, etc)
• take the rfc
• implement in an Bruno-app

Level 3

When API needs to be described not only for inhouse development, but also for external developers/integrators, a simple description of request parameters will no longer suffice.
External developers need to provide examples of filling in the parameters and possible API response options.

coming soon, content in developing...