Back-end service

This is a restful back-end application that allows for querying and mutation GenoBank.io website data and uses 0xcert blockchain gateway endpoint for reading from and writing to Ethereum blockchain.

Authentication

All API routes are publicly exposed and anyone can read from and write to the endpoint.

Requests

The server speaks JSON. It’s recommended that every call to the server includes a ContentType header set to application/json; charset=utf-8;.

Requests with POST or PUT method must send data as application/json or multipart/form-data when files are included in the request body.

$ curl -X 'POST' ... \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{}'

Responses

Every response has a unique ID which helps to identify potential problems. It also includes a status code that can help identifying the cause of a potential problem.

Successful requests include a data key, which holds a valid response object, and a meta key, which holds additional information about the result.

{
  "id": ...,
  "status": ...,
  "data": { ... },
  "meta": { ... },
}

In case of failure, the server responds with errors key, which holds a list of error objects.

{
  "id": ...,
  "status": ...,
  "errors": [ ... ]
}

Query requests through GET method can return status codes 200, 400, 401, 403 or 500. Mutations through POST, PUT and DELETE can return also codes 201 and 422. Invalid routes return status code 404.

• 200: Success.
• 201: Successfully created.
• 400: Invalid resource or resource not found.
• 401: Unauthenticated access.
• 403: Unauthorized access.
• 404: Path not found.
• 422: Data validation failed.
• 500: System error.

Error Handling

Errors include a unique code number and an error message. The code number helps identifying potential problems and points to the exact position in the system.

{
  ...
  "errors": [
    {
      "code": 400004,
      "message": "Invalid path."
    }
  ]
}

Routes

Permittees

An permittee is an Ethereum wallet address of a person who owns a biosample token on the blockchain.

POST /permittees/:permitteeId/:permetteeAddress

Creates a new permittee token on the Ethereum blockchain. The request is sent to the blockchain gateway which handles the interaction with the Ethereum blockchain.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Permittee” section.
• Enter a unique Permittee ID integer number which will uniquely represent a customer.
• Enter a Permittee Address which represents an Ethereum wallet address of a customer. Make sure the address starts without 0x.
• Enter the App secret that is used by the back-end server for encoding tokens and other secrets.
• Click on the Create permittee button to generate the permittee artifacts.
• Configure the request’s permitteeId and permitteeAddress parameters with the provided values.
• Configure the request’s body variable permitteeSecret with the provided value.

NOTICE: The created transaction will not immediately be available for querying. The request will be first sent to the blockchain and when the transaction is confirmed, the permittee record will be created in the database.

Path variables

Body keys

POST /permittees/:permitteeId/public-key

Adds a public key to an existing permittee.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Permittee” section.
• Enter a unique Permittee ID integer number which will uniquely represent a customer.
• Click on the Sign permittee message button to generate the permittee artifacts.
• Configure the request’s permitteeId parameter with the provided values.
• Configure the request’s body variables signature and signatureKind with the provided value.

NOTICE: The wallet address with which permittee message is signed need to be equals to created permittees permitteeAddress.

Path variables

Body keys

GET /permittees/

Returns a paginated list of created permittee objects.

NOTICE: Note that an permittee document is created after its blockchain transaction is confirmed.

Query parameters

GET /permittees/:serial

Returns permittee object details.

NOTICE: Note that an permittee document is created after its blockchain transaction is confirmed.

Path variables

Biosamples

Each biosample is represented by a biosample token on the Ethereum blockchain.

POST /claim/:tokenId

Creates new biosample and permission token on the Ethereum blockchain. The permission token is automatically assigned to a customer’s wallet address.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Biosample” section.
• Enter a unique Biosample ID integer number which uniquely represents a product.
• Enter a Permittee ID which represents an a customer.
• Enter the App secret that is used by the back-end server for encoding tokens and other secrets.
• Click on the Create biosample.
• Configure the request’s body by setting the signature, signatureKind and seed keys with the provided values.
• Configure the request’s tokenId parameter with the provided value.
• Configure the request’s body variable biosampleSecret with the provided value.

NOTICE: The created transactions will not immediately be available for querying. The request will be first sent to the blockchain and when the transaction is confirmed, the biosample and access records record will be created in the database.

Path variables

Body keys

GET /biosamples

Returns a paginated list of created biosample objects.

NOTICE: Note that a biosample document is created after its blockchain transaction is confirmed.

Query parameters

GET /biosamples/:serial

Returns biosample object details.

NOTICE: Note that a biosample document is created after its blockchain transaction is confirmed.

Path variables

Permissions

Each entity has a permission on the blockchain to access a biosample.

POST /permissions/:tokenId

Creates new permission token on the Ethereum blockchain for a customer.

Note that this functionality is also included in the “Create biosample” route.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Permission” section.
• Enter the Biosample ID integer number which uniquely represents a product.
• Enter the Permittee ID which represents a customer.
• Click on the Sign permission button.
• Configure the request’s body by setting the signature, signatureKind and seed keys with the provided values.
• Configure the request’s tokenId parameter with the provided value.

NOTICE: The created transaction will not immediately be available for querying. The request will be first sent to the blockchain and when the transaction is confirmed, the permission document will be created in the database.

Path variables

Body keys

GET /permissions

Returns biosample object details.

NOTICE: Note that a biosample document is created after its blockchain transaction is confirmed.

Query parameters

GET /permissions/:serial

Returns biosample object details.

NOTICE: Note that a biosample document is created after its blockchain transaction is confirmed.

Path variables

Profiles

Each customer has its own profile.

PUT /profiles/:serial

Creates new profile for a customer.

Path variables

Body keys

GET /profiles

Returns a paginated list of profiles.

Query parameters

GET /profiles/:serial

Returns profile object details.

Path variables

Token status

All blockchain transactions refer to the same smart contract. This means that all created tokens have the same structure. The status of these tokens is managed by status routes.

POST /status/:tokenId

Updates token status.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Status” section.
• Enter the Biosample ID integer number which uniquely represents a product.
• Enter the Permittee ID which represents a customer.
• Click on the Change status button.
• Configure the request’s body by setting the signature, signatureKind, seed and uri keys with the provided values.
• Configure the request’s tokenId parameter with the provided value.

NOTICE: Note that documents are updated after the blockchain transactions are confirmed.

Path variables

Body keys

Documents

Arbitrary documents are uploaded to AWS S3 bucket.

GET /documents

Returns a paginated list of created document objects.

Query parameters

GET /documents/:docId

Returns document object details.

Path variables

POST /documents

Uploads an arbitrary JSON object to the cloud. This routes accepts multipart/form-data content type.

Body keys

POST /documents/:docId

Downloads a specific document.

You will need to generate some artifacts to perform this request. Follow the steps below to perform this request:

• Navigate to https://admin.genobank.io.
• Scroll down to the “Download file” section.
• Enter the Document ID value which uniquely identifies an encrypted document.
• [Optional] Enter your Private key (MetaMask will be used if not provided).
• Click on the Download button.
• Configure the request’s body by setting the signature, signatureKind, and timestamp keys with the provided values.

Path variables

Certificates

Each biosample is represented by a biosample token on the Ethereum blockchain.

POST /certificates

Validates info, timestamps and signs it. If a certificate with the same signature already exists it just return information from that certificate.

GET /certificates

Returns a paginated list of created certificate objects.

Query parameters

Counters

Daily counters of creates certificates and biosamples for permittees.

GET /counters

Returns a paginated list of daily counters.

Query parameters

Counter Kinds