Add raml API specification #6
Conversation
maretskiy
left a comment
maretskiy
left a comment
There was a problem hiding this comment.
Why runbooks write-requests contains forms data instead of JSON (like in other projects)? This is very strange to me
| title: Read Only Runbook API Service | ||
| version: v1 | ||
| mediaType: application/json | ||
| baseUri: /api/{version} |
There was a problem hiding this comment.
baseUri must include protocol and hostname.
(conform to the URI specification [RFC2396] or a Level 1 Template URI as defined in RFC 6570)
https://github.com/raml-org/raml-spec/blob/0.8/raml-0.8.md#base-uri-and-baseuriparameters
By the way Abao uses baseUri as default endpoint so this can simplify Abao CLI args on gates further if set to this value:
baseUri: http://127.0.0.1:5000/api/{version}
There was a problem hiding this comment.
yeah, looks like you're right. I just wanted to use it as a shorthand, will remove
| runbook_id: | ||
| description: Id of a particular runbook | ||
| type: string | ||
| put: |
There was a problem hiding this comment.
This is not clear to me, how runbook_id could be known before PUT is complete? Normally, all PUT requests are made for the same URL (for example .../region/{region}/runbooks) and runbook_id of created runbook is returned with the PUT response, isn't it?
There was a problem hiding this comment.
Normally, all PUT requests are made for the same URL
well, no. This url allows altering a specific runbook, so you already know the resource id.
as per RFC
The PUT method requests that the state of the target resource be
created or replaced with the state defined by the representation
enclosed in the request message payload
so a PUT request to .../runbooks should replace the entire collection with another collection.
https://en.wikipedia.org/wiki/Representational_state_transfer#Relationship_between_URL_and_HTTP_methods this article gives a nice overview on how restfull api's usually correspond to http methods
or this article http://restful-api-design.readthedocs.io/en/latest/methods.html#standard-methods
Usually PUT is used on resource-scope, not collection
| description: Update contents of a runbook | ||
| body: | ||
| application/json: | ||
| formParameters: !include forms/runbook.yaml |
There was a problem hiding this comment.
Whty forms???? This is not a request from a WEB page! This is simple JSON data in the request body. No form-encoded data.
There was a problem hiding this comment.
how would you describe which parameters are acceptable and which are mandatory? it's a form with application/json type request
No description provided.