[iks-community] Some guidelines to document API of RESTful services

[Fabian Christ]

Hi,

I also agree with Oliver's approach. Sounds like a usable approach to get started.

Bertrand Delacretaz wrote:
> I'd go further and provide automated test cases (using dummy semantic
> plugins if needed) that actually demonstrate how the API work, and
> verify that it does.
>
> That's not always possible (like: if we don't have an implementation
> yet;-) but if you can do that that's the best way of "documenting" all
> the actual details.

Because it's not always possible to write a concrete runnable test case we
should document the post-condition for each operation. Using this information we
can create (or eventually generate) automated positive test cases.

In case of the RESTful API the pre-conditions are not that important. I think
the pre-conditions are already covered by defining the parameters and their
possible values.

Beside pre- and post-conditions we should also document the known exceptions
that can be raised. Or is this already covered by describing the payload schema?
Only by describing the exceptions we will be able to create automated negative
test cases.

Best regards,
Fabian