Testing the endpoints with Postman
We have attached a postman collection in this repository to showcase how to perform the calls to an AWS App Runner instance that is running this service.
You can get postman from their official website.
With postman, you can then import the circuloos.postmanCollection.json in this repository.
You will either want to download the file by clicking the download button:
Or you can get a URL directly to the file on GitHub by clicking on the raw button when viewing the file:
To import the file so, you will want to open postman, then on the top left click on File then click on Import..., or alternatively use the Ctrl+O default key bind to import:
You can then select the file you downloaded, or paste the URL of the raw file on GitHub (example URL: https://raw.githubusercontent.com/alastria/Circuloos/main/circuloos.postmanCollection.json?token=GHSAT0AAAAAACSCHFJ2ITWIEZS2T4O5PXFWZSW65NA):
Postman will then automatically import the collection, and it will now be usable by you to test:
Before you are able to execute any tests, you will have to get an API Key from us.
If you already have an API Key, then in postman, within the collection itself, you should navigate to the variables tab:
You will see 2 variables, the host (to what server postman will send the requests to) and the api-key (to authenticate to the instance we deployed in AWS App Runner).
You will want to paste your API Key directly into the current value of the api-key variable like so:
Dont forget to save the change you just made either with Ctrl+S or by pressing the Save button!
Once you have done this, the collection is set up, and you can start running the tests.
There are a total of 4 requests prepared in this postman collection, 2 for each Smart Contract that is deployed with this application.
The first Smart Contract is the Single Storage, which stores a single value of the type String, or in other words: any character or sequence of characters that you can typically type on your keyboard can be stored within it.
The second Smart Contract is the Struct Storage, which stores an object defined in the contract. This object can have many individual values, but for the purposes of this example, it only stores 2:
-
storedHash, which is aString, and like before, can store any character or sequence of characters that you can typically type on your keyboard -
number, which is an unsigned 256-bit integer (a number that can store the values from 0 to (2^256)-1 [also known as the very long number: 115,792,089,237,316,195,423,570,985,008,687,907,853,269,984,665,640,564,039,457,584,007,913,129,639,935] )
There are 2 tests for single data type storage, a GET request named Single Storage - Retrieve Value which will read the single value the smart contract is storing and return it to you, and a POST request named Single Storage - Store Value which will write the single value in the body of the request to the smart contract.
The first test you should run is the GET request named Single Storage - Retrieve Value.
This should return you an initial value that is stored, or an empty response if there is nothing currently stored.
To run it, you will first have to open the request by clicking on it:
Once you have it open, simply clicking on Send should run the test:
If all went well, you should be able to see a result on the bottom of your screen.
This result details if everything went well, as well as the response from the service:
You can see in the image that there is a Status: 200 OK on the response.
If you have it saying Status: 403 Forbidden, go back to Setting up the collection and make sure the API key is correct, with no additional spaces or characters, and that you saved the collection.
Example of it saying Status: 403 Forbidden:
Once you have ran the first test, you can then run the second test, which is the POST request named Single Storage - Store Value.
With this test, you can change the stored value that the first test returned for you.
To run it, you will first have to open the request by clicking on it:
Once you have it open, navigate to the Body tab within the request.
You will be able to see an example as to how you can update the value within the Smart Contract:
Feel free to change the value in between the double quotes (") to something else.
Once you are ready, you can run the request by pressing the Send button:
If all went well, you should be able to see a new result on the bottom of your screen.
This result provides you with the transaction receipt from the blockchain after executing the smart contract:
You can see in the image that there is a Status: 200 OK on the response.
If you have it saying Status: 403 Forbidden, go back to Setting up the collection and make sure the API key is correct, with no additional spaces or characters, and that you saved the collection.
Example of it saying Status: 403 Forbidden:
And that is it for the Single Storage tests, you can re-run the GET request if you wish in order to see the updated value.
There are 2 tests for the Struct data type storage, a GET request named Struct Storage - Retrieve Value which will read the Struct value the smart contract is storing and return it to you, and a POST request named Struct Storage - Store Value which will write the Struct value in the body of the request to the smart contract.
The first test you should run is the GET request named Struct Storage - Retrieve Value.
This should return you an initial value that is stored at all times, in the form of a JSON Object.
To run it, you will first have to open the request by clicking on it:
Once you have it open, simply clicking on Send should run the test:
If all went well, you should be able to see a result on the bottom of your screen.
This result details if everything went well, as well as the response from the service:
As you can see, the result differs from the Single Storage, as we get a JSON Object rather than just one value
You can see in the image that there is a Status: 200 OK on the response.
If you have it saying Status: 403 Forbidden, go back to Setting up the collection and make sure the API key is correct, with no additional spaces or characters, and that you saved the collection.
Example of it saying Status: 403 Forbidden:
Once you have ran the first test, you can then run the second test, which is the POST request named Struct Storage - Store Value.
With this test, you can change the stored value that the first test returned for you.
To run it, you will first have to open the request by clicking on it:
Once you have it open, navigate to the Body tab within the request.
You will be able to see an example as to how you can update both values within the Smart Contract:
Feel free to change either or both values in between the double quotes (") to something else.
Once you are ready, you can run the request by pressing the Send button:
If all went well, you should be able to see a new result on the bottom of your screen.
This result provides you with the transaction receipt from the blockchain after executing the smart contract:
You can see in the image that there is a Status: 200 OK on the response.
If you have it saying Status: 403 Forbidden, go back to Setting up the collection and make sure the API key is correct, with no additional spaces or characters, and that you saved the collection.
Example of it saying Status: 403 Forbidden:
And that is it for the Struct Storage tests, you can re-run the GET request if you wish in order to see the updated value.