![]()
IL2 Assets API Basics
### What is IL2 Assets API
The **IL2 Assets API** is the RESTful API defined by the **IL2 Assets** that can be used by applications to manage assets and wallets in a given **IL2 Assets** instance.
Before you start
- To fully understand this presentation, you need to have:
- Basic knownledge about RESTful WebServices;
- Basic knowledge about the IL2 Assets application, see Introduction to IL2 Assets for further information;
- A running instance of the IL2 Assets or the IL2 Assets Simulator with a valid APIKey;
### On-Line documentation
Both **IL2 Assets** and **IL2 Assets Simulator** have an on-line help based on the OpenAPI 3.x standard.
To access it, just open a web browser in the base address of the server and it will be displayed.
> To use some of those APIs, a proper APIKey may be required.
On-Line documentation
![]()
REST API clients
IL2 Network provides REST clients for some products for free. Visit our GitHub to look for them.
If the client you need is not available there, it is possible to automatically generate it from the OpenAPI 3.x definition (openapi.json).
The OpenAPI Generator is an OSS tool that can be used to generate the clients for your favorite language.
### REST API Authentication
- Most of the read-only APIs do not require authentication;
- Those which create/update data or are related to securty credentials do need authentication;
- The authenticaiton is performed through APIKeys;
- The APIKey is provided to the API using the `Authorization` header with the `Bearer` scheme;
Swagger Authentication
On the top-left of the page, click in the button authorize:
![]()
Swagger Authentication
On this dialog box, put the APIKey value and click on the button Authorize to confirm.
![]()
Swagger Authentication
On this dialog box, put the APIKey value and click on the button Authorize to confirm.
![]()
From now on, all API calls will be authorized.
### Programming the authentication
The authentication is performed by sending the HTTP request header `Authorization` with the **APIKey** for all requests:
```text
Authorization: Bearer <put the APIKey here>
```
For example:
```text
Authorization: Bearer <VoA3viomG2IsSbpgzfgdKhTLwqOIr0_6bIZUGgjqLKU>
```
### REST API Categories
- There are 4 categories inside the **IL2 Assets** API:
- meta: Information about the server itself;
- assets: Asset management;
- wallets: Wallet management;
- apikeys: APIKey management;
### GET /rest/v1/version (meta)
Returns the version of the server.
Example:
```json
{
"name": "IL2 Assets Simulator",
"version": "0.1.1"
}
```
### GET /rest/v1/assets/ (assets)
Returns a list of the registered assets.
Example:
```json
{
"offset": 0,
"total": 1,
"entries": [
{
"assetId": "ABCDEFGHIJKLM",
"name": "SOBEIT",
"type": "GENERIC"
}
]
}
```
### POST /rest/v1/assets/ (assets)
Creates a new asset.
It requires a key with `ASSET_MANAGE` permission.
Before calling this method, it is necessary to have at least one issuer wallet
and one burner wallet to be assigned to this asset.
### POST /rest/v1/assets/ (assets)
The request requires a JSON that describes the properties of the asset such as:
- Name: The name of the asset;
- Asset type: The type of the asset;
- Decimal places: unit subdivisions;
- Expiration policy: the expiration policy;
- External Reference: an optional external reference;
- Issuers: list of issuers. At least one is required;
- Burners: list of burners. At least one is required;
### POST /rest/v1/assets/ (assets)
Returns a JSON with the newly created asset:
- Asset ID: The ID assigned to the asset;
- Version: Version of this definition;
- Address: Address of the IL2 block that contains this definition;
### GET /rest/v1/assets/{assetId} (assets)
Returns the information about the given asset.
### PATCH /rest/v1/assets/{assetId} (assets)
Modifies the parameters of the asset.
It requires a key with `ASSET_MANAGE` permission.
Each call to this method will generate new versions of the asset definition.
### PATCH /rest/v1/assets/{assetId} (assets)
Only the following parameters can be updated:
- Expiration policy: the expiration policy;
- External Reference: an optional external reference;
- Issuers: list of issuers. At least one is required;
- Burners: list of burners. At least one is required;
The parameters that are not present in the request will not be updated.
### PATCH /rest/v1/assets/{assetId} (assets)
The list of issuers and burners, if present, will replace the list of active issuers/burners:
- New burners/issuers will be added;
- Existing burners/issuers:
- not in the new list will be deactivated;
- in the new list will be marked as active;
Inactive issuer/burner will retain the assets up to this point but will not be able to issue/burn new assets.
### PATCH /rest/v1/assets/{assetId} (assets)
Once an asset definition is modified, a new version is attributed to it.
The new properties will affect only assets issued after the change. All assets issued before will retain the properties they had at the moment they were created.
### POST /rest/v1/assets/{assetId}/issue (assets)
Issues a certain amount of the spefified asset.
It requires a key with `ASSET_ISSUE` permission.
The assets will be issued using the current version of the asset definition.
### POST /rest/v1/assets/{assetId}/issue (assets)
The request parameters are:
- Amount: the amount to be issued;
- Issuer: The issuer wallet to use. If not is provided, one of the active issuers will be selected randomly;
- expirationDate: required if the expiration policy is CUSTOM otherwise the parameter is ignored;
### POST /rest/v1/assets/{assetId}/issue (assets)
It returns the address of the block that contains the newly issued assets.
The amount issued will be added to the existing balance.
Each issuer wallet keeps the history of all assets issued regardless of the current balance in the wallet.
A issuer wallet can be used to issue more than one asset with no problems.
### GET /rest/v1/assets/{assetId}/issued (assets)
Returns a report with the total amount issued for a given asset.
It includes all issuer wallets, even those which are not active.
### GET /rest/v1/assets/{assetId}/burned (assets)
Returns a report with the total amount officialy burned for a given asset.
It includes all burner wallets, even those which are not active.
Since assets can expired inside issuer an user wallets, not all *burned* assets will be stored in the burner wallets.
### POST /rest/v1/wallets/ (wallets)
Creates a new wallet. It returns the new wallet ID.
It requires a key with `WALLET_MANAGE` permission.
It is important to store the wallet ID because the system does not keep track of them.
Only a single wallet can be stored inside a given chain.
### GET /rest/v1/wallets/{walletId} (wallets)
Returns the information about a given wallet.
It lists all assets current stored on it.
### DELETE /rest/v1/wallets/{walletId} (wallets)
Closes the chain that contains the given wallet. Once a wallet is closed, all assets inside it will be permanently lost.
It requires a key with `WALLET_MANAGE` permission.
THIS OPERATION CANNOT BE UNDONE. USE IT ONLY WHEN NECESSARY.
### GET /rest/v1/wallets/{walletId}/{assetId} (wallets)
Returns detailed information about a given asset inside the given wallet.
All information, including expiration dates and multiple versions of the assets inside the wallet will be recoverd with this method.
### POST /rest/v1/wallets/{walletId}/{assetId}/transfer (wallets)
Transfer a given ammount of the given asset to another wallet.
It requires a key with `WALLET_TRANSFER` permission.
Once this operation is confirmed, it cannot be undone.
### POST /rest/v1/wallets/{walletId}/{assetId}/transfer (wallets)
This method also generates a transfer notification that will be sent to the destination wallet owner.
It returns the block that contains the transference. This information can be used as a receipt of the transference.
### POST /rest/v1/wallets/{walletId}/{assetId}/burn (wallets)
Transfer a given ammount of the given asset to a burner wallet.
It requires a key with `WALLET_TRANSFER` permission.
Once this operation is confirmed, it cannot be undone.
### POST /rest/v1/wallets/{walletId}/{assetId}/burn (wallets)
If a burner is not defined on the request, a random one will be selected from the list of active burners.
This method also generates a transfer notification that will be sent to the destination wallet owner.
It returns the block that contains the transference. This information can be used as a receipt of the transference.
### POST /rest/v1/wallets/{walletId}/{assetId}/burn (wallets)
It is also possible to burn assets using the transfer method. Just set the target wallet to a valid burner wallet.
### GET /rest/v1/wallets/{walletId}/{assetId}/transactions (wallets)
Returns the list of known transactions from the given wallet and asset.
It is important to notice that the transaction information is guaranteed
to be available only for wallets that belong to the current organization.
### GET /rest/v1/wallets/{walletId}/{assetId}/transactions (wallets)
Information about wallets from other organizations may be available too but
it is not guaranteed to be up to date.
The number of days between the startDate and endDate cannot be larger than 31 days.
### GET /rest/v1/assets/ (assets)
Returns a list of the registered assets.
Example:
```json
Response body
Download
{
"walletId": "4xTJR60DpEnWpOyh1Ac174hvF_RdB2tdef7D7SpW2W0",
"assetId": "CIBKXC3VPUS4M",
"startDate": "2023-02-26T22:16:12.0756723Z",
"endDate": "2023-03-13T22:16:12.0756723Z",
"transactions": [
{
"blockId": 153,
"timestamp": "2023-03-13T20:46:53.6963597Z",
"operation": "D",
"otherWalletId": "sVvmXkXZHKpelcxlnDwvO6vJSk3n19HLxnNyFniARBs",
"otherBlockId": 701,
"amount": "1234.56",
"balance": "1234.56"
},
{
"blockId": 420,
"timestamp": "2023-03-13T20:47:12.264956Z",
"operation": "D",
"otherWalletId": "sVvmXkXZHKpelcxlnDwvO6vJSk3n19HLxnNyFniARBs",
"otherBlockId": 1141,
"amount": "10000.00",
"balance": "11234.56"
}
]
}
```
### APIKey management
All methods of the APIKey management requires a key with `APIKEY_MANAGE` permission.
See the on-line help for more information about those methods for more infomration about how to use them.
### Asset lifecycle example
1. Create at least one issuer and one burner wallet;
2. Create the asset definition;
3. Crate at least one user and/or redeem wallet;
4. Issue a certain amount of the newly created asset;
5. Transfer assets from the issuer wallet to to other wallets;
6. Transfer assets to other wallets;
7. Burn the asset when it is no longer required;
### General business rules/hints
1. Issuer and user wallets can only hold non expired assets;
2. Assets that have the same ID but distinct versions and/or expiration dates are fungible but accounted as distinct entities;
3. Assets are transferd from one wallet to another using the expiration date as the priority. Those which expires first are always transfered first;
### Security Properties
Only the owner of the chain can start operations on it:
- If you don't own the asset definition chain, you cannot create nor modify assets;
- If you don't own the chain with a given wallet you cannot perform operations on it;
### Other security considerations
- Once an operation is started, it cannot be undone but it can be amended;
- All transactions are fully auditable as long as the information is on-chain;
- The responsibility to verify the correctness of the transaction information is always assigned to the receiving end;
### Other security considerations (cont.)
- IL2 does not guarantee that the information stored on it is the absolute truth but it ensures that its immutable and non-repudiable;
- Any attempt to commit a fraud will generate proofs against those who are trying to commit a fraud;
- The **IL2 Assets** protocol does not protect the information about the transactions but the privacy may be achieved by holding back the information about the true owner of the wallets;
