forked from digital-asset/daml
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
move ledger-service/http-json docs into docs.daml.com tree, summarize…
… purpose (digital-asset#3012) * verbatim move http-json docs to doc tree * add json-api index to toc, convert md to rst * better links * sub-doc links, proper code inline * replace headings according to README.md * restore newlines * one more newline * point to rst docs from readme * explain purpose of the JSON API and each endpoint * daml-head not needed anymore, as in release * oops 2 newlines
- Loading branch information
Showing
6 changed files
with
328 additions
and
272 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,293 @@ | ||
| .. Copyright (c) 2019 The DAML Authors. All rights reserved. | ||
| .. SPDX-License-Identifier: Apache-2.0 | ||
| HTTP JSON API Service | ||
| ##################### | ||
|
|
||
| **WARNING:** the HTTP JSON API described in this document is actively | ||
| being designed and is *subject to breaking changes*, including all | ||
| request and response elements demonstrated below or otherwise | ||
| implemented by the API. We welcome feedback about the API on `our issue | ||
| tracker | ||
| <https://github.com/digital-asset/daml/issues/new?milestone=HTTP+JSON+API+Maintenance>`_ | ||
| or `on Slack <https://damldriven.slack.com/>`_. | ||
|
|
||
| The JSON API provides a significantly simpler way than :doc:`the Ledger | ||
| API </app-dev/index>` to access *basic active contract set | ||
| functionality*: | ||
|
|
||
| - creating contracts, | ||
| - exercising choices on contracts, and | ||
| - querying the current active contract set. | ||
|
|
||
| The goal is to get you up and running writing effective | ||
| ledger-integrated applications quickly, so we have deliberately excluded | ||
| complicating concerns, including but not limited to | ||
|
|
||
| - inspecting transactions, | ||
| - asynchronous submit/completion workflows, | ||
| - temporal queries (e.g. active contracts *as of a certain time*), and | ||
| - ledger metaprogramming (e.g. packages and templates). | ||
|
|
||
| For these and other features, use :doc:`the Ledger API </app-dev/index>` | ||
| instead. | ||
|
|
||
| .. toctree:: | ||
| :hidden: | ||
|
|
||
| lf-value-specification | ||
| search-query-language | ||
|
|
||
| How to start | ||
| ************ | ||
|
|
||
| Start sandbox from a DAML project directory | ||
| =========================================== | ||
|
|
||
| :: | ||
|
|
||
| $ daml sandbox --wall-clock-time --ledgerid MyLedger ./.daml/dist/quickstart-0.0.1.dar | ||
|
|
||
| Start HTTP service from a DAML project directory | ||
| ================================================ | ||
|
|
||
| :: | ||
|
|
||
| $ daml json-api --ledger-host localhost --ledger-port 6865 \ | ||
| --http-port 7575 --max-inbound-message-size 4194304 --application-id HTTP-JSON-API-Gateway | ||
|
|
||
| Where: | ||
|
|
||
| - localhost 6865 -- sandbox host and port | ||
| - 7575 -- HTTP service port | ||
| - 4194304 -- max inbound message size in bytes (the max size of the message received from the ledger). To set the same limit on the sandbox side, use ``--maxInboundMessageSize`` command line parameter. | ||
|
|
||
| Example session | ||
| *************** | ||
|
|
||
| :: | ||
|
|
||
| $ daml new iou-quickstart-java quickstart-java | ||
| $ cd iou-quickstart-java/ | ||
| $ daml build | ||
| $ daml sandbox --wall-clock-time --ledgerid MyLedger ./.daml/dist/quickstart-0.0.1.dar | ||
| $ daml json-api --ledger-host localhost --ledger-port 6865 --http-port 7575 | ||
|
|
||
| Choosing a party | ||
| ================ | ||
|
|
||
| You specify your party and other settings with JWT. In testing | ||
| environments, you can use https://jwt.io to generate your token. | ||
|
|
||
| The default "header" is fine. Under "Payload", fill in:: | ||
|
|
||
| { | ||
| "ledgerId": "MyLedger", | ||
| "applicationId": "foobar", | ||
| "party": "Alice" | ||
| } | ||
|
|
||
| Keep in mind: | ||
| - the value of ``ledgerId`` payload field has to match ``--ledgerid`` passed to the sandbox. | ||
| - you can replace ``Alice`` with whatever party you want to use. | ||
|
|
||
| Under "Verify Signature", put ``secret`` as the secret (_not_ base64 | ||
| encoded); that is the hardcoded secret for testing. | ||
|
|
||
| Then the "Encoded" box should have your token; set HTTP header | ||
| ``Authorization: Bearer copy-paste-token-here``. | ||
|
|
||
| Here are two tokens you can use for testing: | ||
|
|
||
| - ``{"ledgerId": "MyLedger", "applicationId": "foobar", "party": "Alice"}`` | ||
| ``eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsZWRnZXJJZCI6Ik15TGVkZ2VyIiwiYXBwbGljYXRpb25JZCI6ImZvb2JhciIsInBhcnR5IjoiQWxpY2UifQ.4HYfzjlYr1ApUDot0a6a4zB49zS_jrwRUOCkAiPMqo0`` | ||
|
|
||
| - ``{"ledgerId": "MyLedger", "applicationId": "foobar", "party": "Bob"}`` | ||
| ``eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsZWRnZXJJZCI6Ik15TGVkZ2VyIiwiYXBwbGljYXRpb25JZCI6ImZvb2JhciIsInBhcnR5IjoiQm9iIn0.2LE3fAvUzLx495JWpuSzHye9YaH3Ddt4d2Pj0L1jSjA`` | ||
|
|
||
| For production use, we have a tool in development for generating proper | ||
| RSA-encrypted tokens locally, which will arrive when the service also | ||
| supports such tokens. | ||
|
|
||
| GET http://localhost:7575/contracts/search | ||
| ========================================== | ||
|
|
||
| POST http://localhost:7575/contracts/search | ||
| =========================================== | ||
|
|
||
| List currently active contracts that match a given query. | ||
|
|
||
| application/json body, formatted according to the :doc:`search-query-language`:: | ||
|
|
||
| {"%templates": [{"moduleName": "Iou", "entityName": "Iou"}], | ||
| "amount": 999.99} | ||
|
|
||
| empty output:: | ||
|
|
||
| { | ||
| "status": 200, | ||
| "result": [ | ||
| { | ||
| "offset": "130", | ||
| "activeContracts": [] | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| output, each contract formatted according to :doc:`lf-value-specification`:: | ||
|
|
||
| { | ||
| "status": 200, | ||
| "result": [ | ||
| { | ||
| "offset": "", | ||
| "workflowId": "Alice Workflow", | ||
| "activeContracts": [ | ||
| { | ||
| "agreementText": "", | ||
| "contractId": "#221:0", | ||
| "templateId": { | ||
| "packageId": "ac3a64908d9f6b4453329b3d7d8ddea44c83f4f5469de5f7ae19158c69bf8473", | ||
| "moduleName": "Iou", | ||
| "entityName": "Iou" | ||
| }, | ||
| "witnessParties": [ | ||
| "Alice" | ||
| ], | ||
| "argument": { | ||
| "observers": [], | ||
| "issuer": "Alice", | ||
| "amount": "999.99", | ||
| "currency": "USD", | ||
| "owner": "Alice" | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "offset": "", | ||
| "workflowId": "Alice Workflow", | ||
| "activeContracts": [ | ||
| { | ||
| "agreementText": "", | ||
| "contractId": "#224:0", | ||
| "templateId": { | ||
| "packageId": "ac3a64908d9f6b4453329b3d7d8ddea44c83f4f5469de5f7ae19158c69bf8473", | ||
| "moduleName": "Iou", | ||
| "entityName": "Iou" | ||
| }, | ||
| "witnessParties": [ | ||
| "Alice" | ||
| ], | ||
| "argument": { | ||
| "observers": [], | ||
| "issuer": "Alice", | ||
| "amount": "999.99", | ||
| "currency": "USD", | ||
| "owner": "Alice" | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "offset": "227", | ||
| "activeContracts": [] | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| POST http://localhost:7575/command/create | ||
| ========================================= | ||
|
|
||
| Create a contract. | ||
|
|
||
| application/json body, ``argument`` formatted according to :doc:`lf-value-specification`:: | ||
|
|
||
| { | ||
| "templateId": { | ||
| "moduleName": "Iou", | ||
| "entityName": "Iou" | ||
| }, | ||
| "argument": { | ||
| "observers": [], | ||
| "issuer": "Alice", | ||
| "amount": "999.99", | ||
| "currency": "USD", | ||
| "owner": "Alice" | ||
| } | ||
| } | ||
|
|
||
| output:: | ||
|
|
||
| { | ||
| "status": 200, | ||
| "result": { | ||
| "agreementText": "", | ||
| "contractId": "#20:0", | ||
| "templateId": { | ||
| "packageId": "bede798df37ce01fc402d266ae89d5bc4c61d70968b6a4f0baf69b24140579aa", | ||
| "moduleName": "Iou", | ||
| "entityName": "Iou" | ||
| }, | ||
| "witnessParties": [ | ||
| "Alice" | ||
| ], | ||
| "argument": { | ||
| "observers": [], | ||
| "issuer": "Alice", | ||
| "amount": "999.99", | ||
| "currency": "USD", | ||
| "owner": "Alice" | ||
| } | ||
| } | ||
| } | ||
| POST http://localhost:44279/command/exercise | ||
| ============================================ | ||
|
|
||
| Exercise a choice on a contract. | ||
|
|
||
| ``"contractId": "#20:0"`` is the value from the create output | ||
| application/json body:: | ||
|
|
||
| { | ||
| "templateId": { | ||
| "moduleName": "Iou", | ||
| "entityName": "Iou" | ||
| }, | ||
| "contractId": "#20:0", | ||
| "choice": "Iou_Transfer", | ||
| "argument": { | ||
| "newOwner": "Alice" | ||
| } | ||
| } | ||
|
|
||
| output:: | ||
|
|
||
| { | ||
| "status": 200, | ||
| "result": [ | ||
| { | ||
| "agreementText": "", | ||
| "contractId": "#160:1", | ||
| "templateId": { | ||
| "packageId": "bede798df37ce01fc402d266ae89d5bc4c61d70968b6a4f0baf69b24140579aa", | ||
| "moduleName": "Iou", | ||
| "entityName": "IouTransfer" | ||
| }, | ||
| "witnessParties": [ | ||
| "Alice" | ||
| ], | ||
| "argument": { | ||
| "iou": { | ||
| "observers": [], | ||
| "issuer": "Alice", | ||
| "amount": "999.99", | ||
| "currency": "USD", | ||
| "owner": "Alice" | ||
| }, | ||
| "newOwner": "Alice" | ||
| } | ||
| } | ||
| ] | ||
| } |
Oops, something went wrong.