search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.65k stars 2.14k forks source link

Parametric Headers Description #26

Closed zdne closed 8 years ago

zdne commented 10 years ago

Documentation of HTTP headers using syntax similar to URI parameters.

e.g.

+ Headers
    + Location (string, `/some/uri`) ... URI of the created user account
ecordell commented 10 years ago

Is there a concept of header validation planned? Common headers have a very specific syntax (like link headers) and most custom headers could be validated with basic type checking or regexes.

zdne commented 10 years ago

@ecordell

Nothing besides what is in Dredd / Gavel. This is mainly a design goal - to get rid of as most of pre code blocks as possible while unifying syntax (=making it easier to learn) for parameters, body attributes and headers...

ecordell commented 10 years ago

@zdne

Do you have thoughts about how header validation should be handled?

It seems like header validation should be supported: If a POST should return a Location header, and the API responds with a valid Location header but which is not the exact location that's documented in the blueprint, Dredd will say that the docs/api are out of sync when they're actually perfectly fine.

Standard headers (like Link) have some default formatting rules they must comply with, so it would be easy to bake in validation for that in Gavel(?). Custom headers or custom validation of standard headers could be validated pretty simply with a regex. Seem reasonable?

The only question then would be if there should be a syntax in the blueprint for saying either 1) the header must contain this value exactly or 2) the header must validate against this pattern (sort of how the Body can match text exactly or a schema).

Edit with possible design: header should match exactly

+ Headers
    + Location (string, `/some/uri`) ... URI of the created user account

header should validate against a regex

+ Headers
    + Location (string, `/some/uri`, `regex_string`) ... URI of the created user account
zdne commented 10 years ago

@ecordell

I feel like writing regexes into blueprint is far from what is readable for most of the users. However some out-of-the-box headers validation would be great.

Note there is already the preliminary support for "header schema" in Gavel. Which leads me to following idea (just brainstorming here):

  1. Support schema in parametric headers syntax (this can include a regex)
  2. Provide default header schemas for some of the know headers https://github.com/for-GET/know-your-http-well/blob/master/headers.md

The parametric headers definition should in fact generate a header schema if not provided. So really the question here is whether add the dedicated syntax for the regexes...

zdne commented 8 years ago

RFC proposal of syntax addressing this issue: https://github.com/apiaryio/api-blueprint-rfcs/pull/3.

Please track and comment on the RFC.

Thank you!