Add section headings to projections HTTP API docs #4101
Conversation
hayley-jean
added
the
area/documentation
docs/http-api/projections.md
Outdated
| ### Create a Continuous Projection | ||
|
|
||
| | URI | Description | HTTP verb | | ||
| |:---------------------------------------------------|:-----------------------------|:----------| | ||
| | `/projections/continuous?name={name}&type={type}&enabled={enabled}&emit={emit}&trackemittedstreams={trackemittedstreams}` | Create a continuous projection. This type of projection will, if enabled will continuously run unless disabled or an unrecoverable error is encountered. | POST | |
There was a problem hiding this comment.
| | `/projections/continuous?name={name}&type={type}&enabled={enabled}&emit={emit}&trackemittedstreams={trackemittedstreams}` | Create a continuous projection. This type of projection will, if enabled will continuously run unless disabled or an unrecoverable error is encountered. | POST | | |
| | `/projections/continuous?name={name}&type={type}&enabled={enabled}&emit={emit}&trackemittedstreams={trackemittedstreams}` | Create a continuous projection. This type of projection will, if enabled, continuously run unless disabled or an unrecoverable error is encountered. | POST | |
docs/http-api/projections.md
Outdated
| @@ -209,6 +221,8 @@ The server then returns the state for the partition: | |||
| * `emit`: Allow the projection to write to streams (true/false) | |||
| * `trackemittedstreams`: Write the name of the streams the projection is managing to a separate stream. $projections-{projection-name}-emittedstreams (true/false) | |||
|
|
|||
| ### Delete a Projection | |||
|
|
|||
| | URI | Description | HTTP verb | | |||
| |:-------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------|:----------| | |||
| | `/projection/{name}` | Returns information for a projection. | GET | | |||
There was a problem hiding this comment.
Shouldn't the verb be delete?
| | `/projection/{name}` | Returns information for a projection. | GET | | |
| | `/projection/{name}` | Returns information for a projection. | DELETE | |
There was a problem hiding this comment.
Ah there were actually two different actions in the table. I think the original formatting was meant to be closer to what's in the most recent commit. It's up to you whether that's more readable than different sections per action @cdevarenne @rsowald 🙂
| @@ -221,6 +235,8 @@ The server then returns the state for the partition: | |||
| * `deleteCheckpointStream`: Delete the checkpoint stream (true/false) | |||
There was a problem hiding this comment.
Should the arguments be shown in the example?
There was a problem hiding this comment.
from the other examples, it looks like just including it in the URI is setting it true. Omitting is false. This is unclear in the documentation though. If that's the case, I think we should just remove the (true/false) from the descriptions. So, it's also unclear if any/all of these parameters are required.
There was a problem hiding this comment.
it looks like just including it in the URI is setting it true. Omitting is false.
@rsowald This isn't always the case. Omitting it is leaving it as the default (which we should list in the parameters), but if you want to set it you should use either deleteCheckpointStream=true or deleteCheckpointStream=false
Should the arguments be shown in the example?
@cdevarenne Do you mean something like this?
/projections/continuous?name={name}&type={ js | native }&enabled={ true | false }&emit={ true | false }&trackemittedstreams={ true | false }
b327a81
to
d1ebd2e
Compare
The HTTP API docs were missing headings for each operation, which makes it difficult to find what you're looking for