Skip to content

Commit c485828

Browse files
GitHubber17GitHubber17
authored
Merge pull request #106707 from PatAltimore/patricka-blockchain-rest
Add POST API details
2 parents d9fa461 + c0217cb commit c485828

File tree

1 file changed

+193
-33
lines changed

1 file changed

+193
-33
lines changed

‎articles/blockchain/workbench/use-api.md

Lines changed: 193 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,14 @@
11
---
22
title: Using Azure Blockchain Workbench REST APIs
33
description: Scenarios for how to use the Azure Blockchain Workbench Preview REST API
4-
ms.date: 10/14/2019
4+
ms.date: 03/05/2020
55
ms.topic: article
66
ms.reviewer: brendal
77
#Customer intent: As a developer, I want to understand the Azure Blockchain Workbench REST API to so that I can integrate apps with Blockchain Workbench.
88
---
99
# Using the Azure Blockchain Workbench Preview REST API
1010

11-
Azure Blockchain Workbench Preview REST API provides developers and information workers a way to build rich integrations to blockchain applications. This document walks you through several key methods of the Workbench REST API. For example, suppose a developer wants to create a custom blockchain client. This blockchain client allows signed in users to view and interact with their assigned blockchain applications. The client allows users to view contract instances and take actions on smart contracts. The client uses the Workbench REST API in the context of the signed-in user to do the following actions:
12-
13-
* List applications
14-
* List workflows for an application
15-
* List smart contract instances for a workflow
16-
* List available actions for a contract
17-
* Execute an action for a contract
18-
19-
The example blockchain applications used in the scenarios, can be [downloaded from GitHub](https://github.com/Azure-Samples/blockchain).
11+
Azure Blockchain Workbench Preview REST API provides developers and information workers a way to build rich integrations to blockchain applications. This article highlights several scenarios of how to use the Workbench REST API. For example, suppose you want to create a custom blockchain client that allows signed in users to view and interact with their assigned blockchain applications. The client can use the Blockchain Workbench API to view contract instances and take actions on smart contracts.
2012

2113
## Blockchain Workbench API endpoint
2214

@@ -31,21 +23,125 @@ Blockchain Workbench APIs are accessed through an endpoint for your deployment.
3123

3224
![App service API endpoint URL](media/use-api/app-service-api.png)
3325

26+
## Authentication
27+
28+
Requests to the Blockchain Workbench REST API are protected with Azure Active Directory (Azure AD).
29+
30+
To make an authenticated request to the REST APIs, client code requires authentication with valid credentials before you can call the API. Authentication is coordinated between the various actors by Azure AD, and provides your client with an [access token](https://docs.microsoft.com/azure/active-directory/develop/active-directory-dev-glossary#access-token) as proof of the authentication. The token is then sent in the HTTP Authorization header of REST API requests. To learn more about Azure AD authentication, see [Azure Active Directory for developers](https://docs.microsoft.com/azure/active-directory/develop/active-directory-developers-guide).
31+
32+
See [REST API samples](https://github.com/Azure-Samples/blockchain/tree/master/blockchain-workbench/rest-api-samples) for examples of how to authenticate.
33+
34+
## Using Postman
35+
36+
If you want to test or experiment with Workbench APIs, you can use [Postman](https://www.postman.com) to make API calls to your deployment. [Download a sample Postman collection of Workbench API requests](https://github.com/Azure-Samples/blockchain/tree/master/blockchain-workbench/rest-api-samples/postman) from GitHub. See the README file for details on authenticating and using the example API requests.
37+
38+
## Create an application
39+
40+
You use two API calls to create a Blockchain Workbench application. This method can only be performed by users who are Workbench administrators.
41+
42+
Use the [Applications POST API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/applicationspost) to upload the application's JSON file and get an application ID.
43+
44+
### Applications POST request
45+
46+
Use the **appFile** parameter to send the configuration file as part of the request body.
47+
48+
``` http
49+
POST /api/v1/applications
50+
Content-Type: multipart/form-data;
51+
Authorization : Bearer {access token}
52+
Content-Disposition: form-data; name="appFile"; filename="/C:/smart-contract-samples/HelloWorld.json"
53+
Content-Type: application/json
54+
```
55+
56+
### Applications POST response
57+
58+
The created application ID is returned in the response. You need the application ID to associate the configuration file with the code file when you call the next API.
59+
60+
``` http
61+
HTTP/1.1 200 OK
62+
Content-Type: "application/json"
63+
1
64+
```
65+
66+
### Contract code POST request
67+
68+
Use the [Applications contract code POST API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/contractcodepost) by passing the application ID to upload the application's Solidity code file. The payload can be a single Solidity file or a zipped file containing Solidity files.
69+
70+
Replace the following values:
71+
72+
| Parameter | Value |
73+
|-----------|-------|
74+
| {applicationId} | Return value from the applications POST API. |
75+
| {ledgerId} | Index of the ledger. The value is usually 1. You can also check the [Ledger table](data-sql-management-studio.md) for the value. |
76+
77+
``` http
78+
POST /api/v1/applications/{applicationId}/contractCode?ledgerId={ledgerId}
79+
Content-Type: multipart/form-data;
80+
Authorization : Bearer {access token}
81+
Content-Disposition: form-data; name="contractFile"; filename="/C:/smart-contract-samples/HelloWorld.sol"
82+
```
83+
84+
### Contract code POST response
85+
86+
If successful, the response includes the created contract code ID from the [ContractCode table](data-sql-management-studio.md).
87+
88+
``` http
89+
HTTP/1.1 200 OK
90+
Content-Type: "application/json"
91+
2
92+
```
93+
94+
## Assign roles to users
95+
96+
Use the [Applications role assignments POST API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/roleassignmentspost) by passing the application ID, user ID, and application role ID to create a user-to-role mapping in the specified blockchain application. This method can only be performed by users who are Workbench administrators.
97+
98+
### Role assignments POST request
99+
100+
Replace the following values:
101+
102+
| Parameter | Value |
103+
|-----------|-------|
104+
| {applicationId} | Return value from the Applications POST API. |
105+
| {userId} | User ID value from the [User table](data-sql-management-studio.md). |
106+
| {applicationRoleId} | Application role ID value associated to the application ID from the [ApplicationRole table](data-sql-management-studio.md). |
107+
108+
``` http
109+
POST /api/v1/applications/{applicationId}/roleAssignments
110+
Content-Type: application/json;
111+
Authorization : Bearer {access token}
112+
113+
{
114+
"userId": {userId},
115+
"applicationRoleId": {applicationRoleId}
116+
}
117+
```
118+
119+
### Role assignments POST response
120+
121+
If successful, the response includes the created role assignment ID from the [RoleAssignment table](data-sql-management-studio.md).
122+
123+
``` http
124+
HTTP/1.1 200
125+
1
126+
```
127+
34128
## List applications
35129

36-
Once a user has signed into the blockchain client, the first task is to retrieve all Blockchain Workbench applications for the user. In this scenario, the user has access to two applications:
130+
Use the [Applications GET API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/applicationsget) to retrieve all Blockchain Workbench applications for the user. In this example, the signed-in user has access to two applications:
37131

38-
1. [Asset transfer](https://github.com/Azure-Samples/blockchain/blob/master/blockchain-workbench/application-and-smart-contract-samples/asset-transfer/readme.md)
39-
2. [Refrigerated transportation](https://github.com/Azure-Samples/blockchain/blob/master/blockchain-workbench/application-and-smart-contract-samples/refrigerated-transportation/readme.md)
132+
- [Asset transfer](https://github.com/Azure-Samples/blockchain/blob/master/blockchain-workbench/application-and-smart-contract-samples/asset-transfer/readme.md)
133+
- [Refrigerated transportation](https://github.com/Azure-Samples/blockchain/blob/master/blockchain-workbench/application-and-smart-contract-samples/refrigerated-transportation/readme.md)
40134

41-
Use the [Applications GET API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/applicationsget):
135+
### Applications GET request
42136

43137
``` http
44138
GET /api/v1/applications
45139
Authorization : Bearer {access token}
46140
```
47141

48-
The response lists all blockchain applications to which a user has access in Blockchain Workbench. Blockchain Workbench administrators get every blockchain application. Non-Workbench administrators get all blockchains for which they have at least one associated application role or an associated smart contract instance role.
142+
### Applications GET response
143+
144+
The response lists all blockchain applications to which a user has access in Blockchain Workbench. Blockchain Workbench administrators get every blockchain application. Non-Workbench administrators get all blockchain applications for which they have at least one associated application role or an associated smart contract instance role.
49145

50146
``` http
51147
HTTP/1.1 200 OK
@@ -79,16 +175,18 @@ Content-type: application/json
79175

80176
## List workflows for an application
81177

82-
Once a user selects the applicable blockchain application (such as **Asset Transfer**), the blockchain client retrieves all workflows of the specific blockchain application. Users can then select the applicable workflow before being shown all smart contract instances for the workflow. Each blockchain application has one or more workflows and each workflow has zero or smart contract instances. For a blockchain client application that has only one workflow, we recommend skipping the user experience flow that allows users to select the appropriate workflow. In this case, **Asset Transfer** has only one workflow, also called **Asset Transfer**.
178+
Use [Applications Workflows GET API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/workflowsget) to list all workflows of a specified blockchain application to which a user has access in Blockchain Workbench. Each blockchain application has one or more workflows and each workflow has zero or smart contract instances. For a blockchain client application that has only one workflow, we recommend skipping the user experience flow that allows users to select the appropriate workflow.
83179

84-
Use the [Applications Workflows GET API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/applications/workflowsget):
180+
### Application workflows request
85181

86182
``` http
87183
GET /api/v1/applications/{applicationId}/workflows
88184
Authorization: Bearer {access token}
89185
```
90186

91-
Response lists all workflows of the specified blockchain application to which a user has access in Blockchain Workbench. Blockchain Workbench administrators get every blockchain workflow. Non-Workbench administrators get all workflows for which they have at least one associated application role or is associated with a smart contract instance role.
187+
### Application workflows response
188+
189+
Blockchain Workbench administrators get every blockchain workflow. Non-Workbench administrators get all workflows for which they have at least one associated application role or is associated with a smart contract instance role.
92190

93191
``` http
94192
HTTP/1.1 200 OK
@@ -109,18 +207,72 @@ Content-type: application/json
109207
}
110208
```
111209

210+
## Create a contract instance
211+
212+
Use [Contracts V2 POST API](https://docs.microsoft.com/rest/api/azure-blockchain-workbench/contractsv2/contractpost) to create a new smart contract instance for a workflow. Users are only able to create a new smart contract instance if the user is associated with an application role, which can initiate a smart contract instance for the workflow.
213+
214+
> [!NOTE]
215+
> In this example, version 2 of the API is used. Version 2 contract APIs provide more granularity for the associated ProvisioningStatus fields.
216+
217+
### Contracts POST request
218+
219+
Replace the following values:
220+
221+
| Parameter | Value |
222+
|-----------|-------|
223+
| {workflowId} | Workflow ID value is the contract's ConstructorID from the [Workflow table](data-sql-management-studio.md). |
224+
| {contractCodeId} | Contract code ID value from the [ContractCode table](data-sql-management-studio.md). Correlate the application ID and ledger ID for the contract instance you want to create. |
225+
| {connectionId} | Connection ID value from the [Connection table](data-sql-management-studio.md). |
226+
227+
For the request body, set values using the following information:
228+
229+
| Parameter | Value |
230+
|-----------|-------|
231+
| workflowFunctionID | ID from the [WorkflowFunction table](data-sql-management-studio.md). |
232+
| workflowActionParameters | Name value pairs of parameters passed to the constructor. For each parameter, use the workflowFunctionParameterID value from the [WorkflowFunctionParameter](data-sql-management-studio.md) table. |
233+
234+
``` http
235+
POST /api/v2/contracts?workflowId={workflowId}&contractCodeId={contractCodeId}&connectionId={connectionId}
236+
Content-Type: application/json;
237+
Authorization : Bearer {access token}
238+
239+
{
240+
"workflowFunctionID": 2,
241+
"workflowActionParameters": [
242+
{
243+
"name": "message",
244+
"value": "Hello, world!",
245+
"workflowFunctionParameterId": 3
246+
}
247+
]
248+
}
249+
```
250+
251+
### Contracts POST response
252+
253+
If successful, role assignments API returns the ContractActionID from the [ContractActionParameter table](data-sql-management-studio.md).
254+
255+
``` http
256+
HTTP/1.1 200 OK
257+
4
258+
```
259+
112260
## List smart contract instances for a workflow
113261

114-
Once a user selects the applicable workflow, this case **Asset Transfer**, the blockchain client will retrieve all smart contract instances for the specified workflow. You can use this information to show all smart contract instances for the workflow. Or you can allow users to deep dive into any of the shown smart contract instances. In this example, consider a user would like to interact with one of the smart contract instances to take action.
262+
Use [Contracts GET API](/rest/api/azure-blockchain-workbench/contractsv2/contractsget) to show all smart contract instances for a workflow. Or you can allow users to deep dive into any of the shown smart contract instances.
115263

116-
Use the [Contracts GET API](/rest/api/azure-blockchain-workbench/contractsv2/contractsget):
264+
### Contracts request
265+
266+
In this example, consider a user would like to interact with one of the smart contract instances to take action.
117267

118268
``` http
119269
GET api/v1/contracts?workflowId={workflowId}
120270
Authorization: Bearer {access token}
121271
```
122272

123-
Response lists all smart contract instances of the specified workflow. Workbench administrators get all smart contract instances. Non-Workbench administrators get every smart contract instance for which they have at least one associated application role or is associated with a smart contract instance role.
273+
### Contracts response
274+
275+
The response lists all smart contract instances of the specified workflow. Workbench administrators get all smart contract instances. Non-Workbench administrators get every smart contract instance for which they have at least one associated application role or is associated with a smart contract instance role.
124276

125277
``` http
126278
HTTP/1.1 200 OK
@@ -210,19 +362,25 @@ Content-type: application/json
210362

211363
## List available actions for a contract
212364

213-
Once a user decides to deep dive into a contract, the blockchain client can then show the available user actions given the state of the contract. In this example, the user is looking at all available actions for a new smart contract they created:
365+
Use [Contract Action GET API](/rest/api/azure-blockchain-workbench/contractsv2/contractactionget) to show the available user actions given the state of the contract.
214366

215-
* Modify: Allows the user to modify the description and price of an asset.
216-
* Terminate: Allows the user to end the contract of the asset.
367+
### Contract action request
217368

218-
Use the [Contract Action GET API](/rest/api/azure-blockchain-workbench/contractsv2/contractactionget):
369+
In this example, the user is looking at all available actions for a new smart contract they created.
219370

220371
``` http
221372
GET /api/v1/contracts/{contractId}/actions
222373
Authorization: Bearer {access token}
223374
```
224375

225-
Response lists all actions to which a user can take given the current state of the specified smart contract instance. Users get all applicable actions if the user has an associated application role or is associated with a smart contract instance role for the current state of the specified smart contract instance.
376+
### Contract action response
377+
378+
Response lists all actions to which a user can take given the current state of the specified smart contract instance.
379+
380+
* Modify: Allows the user to modify the description and price of an asset.
381+
* Terminate: Allows the user to end the contract of the asset.
382+
383+
Users get all applicable actions if the user has an associated application role or is associated with a smart contract instance role for the current state of the specified smart contract instance.
226384

227385
``` http
228386
HTTP/1.1 200 OK
@@ -277,12 +435,11 @@ Content-type: application/json
277435

278436
## Execute an action for a contract
279437

280-
A user can then decide to take action for the specified smart contract instance. In this case, consider the scenario where a user would like to modify the description and price of an asset to the following action:
438+
Use [Contract Action POST API](/rest/api/azure-blockchain-workbench/contractsv2/contractactionpost) to take action for the specified smart contract instance.
281439

282-
* Description: "My updated car"
283-
* Price: 54321
440+
### Contract action POST request
284441

285-
Use the [Contract Action POST API](/rest/api/azure-blockchain-workbench/contractsv2/contractactionpost):
442+
In this case, consider the scenario where a user would like to modify the description and price of an asset.
286443

287444
``` http
288445
POST /api/v1/contracts/{contractId}/actions
@@ -302,7 +459,11 @@ actionInformation: {
302459
}
303460
```
304461

305-
Users are only able to execute the action given the current state of the specified smart contract instance and the user's associated application role or smart contract instance role. If the post is successful, an HTTP 200 OK response is returned with no response body.
462+
Users are only able to execute the action given the current state of the specified smart contract instance and the user's associated application role or smart contract instance role.
463+
464+
### Contract action POST response
465+
466+
If the post is successful, an HTTP 200 OK response is returned with no response body.
306467

307468
``` http
308469
HTTP/1.1 200 OK
@@ -311,5 +472,4 @@ Content-type: application/json
311472

312473
## Next steps
313474

314-
> [!div class="nextstepaction"]
315-
> [Azure Blockchain Workbench REST API reference](https://docs.microsoft.com/rest/api/azure-blockchain-workbench)
475+
For reference information on Blockchain Workbench APIs, see the [Azure Blockchain Workbench REST API reference](https://docs.microsoft.com/rest/api/azure-blockchain-workbench).

0 commit comments

Comments
 (0)