JSON API documentation improvements #4173
Conversation
docs/source/json-api/index.rst
Outdated
| - exercising choices on contracts, and | ||
| - querying the current active contract set. | ||
| - create contract, | ||
| - fetch active contract by contract ID or contract key, |
There was a problem hiding this comment.
Keep the description here informal, describing categories of functionality not enumerating features; fetch is already covered by "query the current active contract set".
docs/source/json-api/index.rst
Outdated
|
|
||
| application/json body, formatted according to the :doc:`search-query-language`: | ||
| If client's HTTP request reaches an API endpoint, the corresponding response will always contain a JSON object with ``status`` field and either ``errors`` or ``result``: |
There was a problem hiding this comment.
| If client's HTTP request reaches an API endpoint, the corresponding response will always contain a JSON object with ``status`` field and either ``errors`` or ``result``: | |
| If client's HTTP GET or POST request reaches an API endpoint, the corresponding response will always contain a JSON object with ``status`` field and either ``errors`` or ``result``: |
docs/source/json-api/index.rst
Outdated
|
|
||
| List all currently active contracts for all known templates. Note that the retrieved contracts do not get persisted into query store database. | ||
| See the following blog post for more details: `REST API Error Codes 101 <https://blog.restcase.com/rest-api-error-codes-101/>`_. |
There was a problem hiding this comment.
It feels strange to me to start with a link to an external blog post. IMO, there should be at least a sentence stating that we use standard REST API error codes or something similar.
docs/source/json-api/index.rst
Outdated
| } | ||
| - ``status`` -- a JSON Number which matches the HTTP response status code returned in the HTTP header, | ||
| - ``errors`` -- a JSON array of strings, each string represents one error, | ||
| - ``result`` -- a JSON object or JSON array, representing one or many results. |
There was a problem hiding this comment.
We have warnings as well now.
| + ``"<package ID>:<module>:<entity>"`` or | ||
| + ``"<module>:<entity>"`` if contract template can be uniquely identified by it's module and entity name. | ||
|
|
||
| - ``argument`` field contains contract fields as defined in the DAML template and formatted according to :doc:`lf-value-specification`. |
There was a problem hiding this comment.
Haven't we renamed this to payload? If not, we should in order to make it consistent.
There was a problem hiding this comment.
@hurryabit it is renamed only in the response. See #3826 :
I suggest we rename the argument field of the contracts you receive from the JSON API to payload.
This particular JSON is a create command, a request sent to JSON API.
There was a problem hiding this comment.
if you want to rename argument to the payload in the requests, this should be addressed in #4189.
docs/source/json-api/index.rst
Outdated
| @@ -569,26 +549,29 @@ Contract Found Response | |||
| } | |||
| } | |||
|
|
|||
| Lookup by Contract Key | |||
| ---------------------- | |||
| Fetch Contract by Contract Key | |||
There was a problem hiding this comment.
| Fetch Contract by Contract Key | |
| Fetch Contract by Key |
docs/source/json-api/index.rst
Outdated
| Contract Search, All Templates | ||
| ============================== | ||
|
|
||
| List all currently active contracts for all known templates. Note that the retrieved contracts do not get persisted into query store database. |
There was a problem hiding this comment.
Is there any explanation of what the "query store database" is? I couldn't find any.
Document error handling Document query store CHANGELOG_BEGIN CHANGELOG_END
leo-da
force-pushed
the
leo-3732-json-api-doc
branch
from
faca5fb to
b8cf409
Compare
Closes: #3732
Pull Request Checklist
CHANGELOG_BEGINandCHANGELOG_ENDtagsNOTE: CI is not automatically run on non-members pull-requests for security
reasons. The reviewer will have to comment with
/AzurePipelines runtotrigger the build.