DEV Community

Cover image for Apillon Features: API calls to Web3 services
Apillon profile image Lenka
Lenka for Apillon

Posted on • Edited on

Apillon Features: API calls to Web3 services

Apillon API delivers a straightforward connectivity to Polkadot parachains while respecting the standard development workflow.

One of the main hinderers of Web3 adoption is the development process. Apillon API shortens the way Web3 products are built by saving developers the trouble of diving into each parachain's specifics, logic, and requirements.

The drawbacks of standard access to Web3

If you decide to code a Web3 project or implement a decentralized service provider to your existing website or app from scratch, you face a steep learning curve and a potentially high risk of things going south.

Wrestling with Web3 bare-handed could be extremely heavy on resources while still not guaranteeing any wins. There are plenty of uncertainties along the way, and every developer, even the Web3 veterans, could easily overlook important steps, ultimately leading to deep frustration and even abandonment of the Web3 mission altogether.

🔎 Learn more about the challenges of building on Web3.

To simplify the development process and bring it to terms every developer should be familiar with, Apillon introduces API connectivity to linked Polkadot parachains and their Web3 services.

Apillon Web3 APIs

Apillon integrates multiple Polkadot parachains and offers straightforward access to linked decentralized services in two ways:

  • A drag-and-drop deployment of Web3 services on the Apillon dashboard
  • API keys

In this post, we will dive into the latter, where Apillon APIs enhance and streamline the coding process of Web3 projects.

What is Apillon API?

Apillon API is a set of RESTful API endpoints that allow you to integrate Apillon Web3 services modules into your Web3 project.

Using Apillon APIs, you make a call to a server and receive the response over the HTTP protocol.

To ensure the privacy and safety of Web3 project development, all routes are private and require you to use an API key.

Now, let's see how to use Apillon APIs when coding your Web3 project.

Apillon API specifics

Requests
The server speaks JSON, and for that reason, every call to the server should include a Content-Type header set to application/json;.

Authentication and authorization
Apillon API routes ensure privacy by restricting public access and requiring authentication.

When creating requests, you should therefore include a basic auth HTTP header field in the form of Authorization: Basic <credentials>, where credentials represent the Base64 encoding of API key and API key secret joined by a single colon :.

You can generate API keys on the Apillon dashboard under Project settings.

apillon-dashboard-api-key-generation
apillon-dashboard-api-key-details

Once generated, you can use the API key in your project.

Responses
Every response has a unique ID to help you identify potential issues in the API connectivity or accessed services. It also includes a status code so you can quickly identify the cause of a potential problem.

Query requests through GET method can return status codes 200, 400, 401, 403, or 500, indicating success, bad request, unauthenticated or unauthorized access, or system error.

Mutations through POST, PUT and DELETE can further return codes 201 and 422, namely successful creation or failed data validation. And, invalid routes return status code 404, indicating path not found.

A successful request includes a data key, which holds a valid response object.

🔎 Learn more about Apillon Web3 API, responses, error handling, and validation in Apillon Wiki.

apillon-api-to-web3-wiki

Now with theory out of the way, let's dive into the contents of APIs connecting to the two Web3 services accessible in the Apillon Beta:

  • Web3 Storage API
  • Web3 Hosting API

☝️ More APIs will be made available in the upcoming versions of the Apillon platform, so stay tuned.

Web3 Storage API

Apillon Web3 Storage API connects to the Crust Network, allowing you to store your files in a decentralized way.

Before you start using the Web3 Storage API, there are two things to keep in mind:

  • You should first create a storage bucket on the Apillon dashboard.
  • In all cURL examples, parameters with a colon as a prefix should be replaced with real values.

File upload process via Apillon Web3 Storage API

The files you store on the Crust Network are uploaded as follows:

  1. Request signed URL(s) for upload.
  2. File is uploaded to Apillon central server.
  3. File is transferred to IPFS and available through the Apillon gateway.
  4. File is replicated to different IPFS nodes globally via Crust Network.

Now, let's do it step by step using Apillon API.

How to use Apillon Web3 Storage API

1. Upload to storage bucket
First, create file upload requests that return URLs for file upload along with sessionUuid.

🔻 cURL

curl --location --request POST "https://api.apillon.io/storage/:bucketUuid/upload" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"files\": [
        {
            \"fileName\": \"My test file\",
            \"contentType\": \"text/html\"
        }
    ]

}"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "cbdc4930-2bbd-4b20-84fa-15daa4429952",
  "status": 201,
  "data": {
    "sessionUuid": "3b6113bc-f265-4662-8cc5-ea86f06cc74b",
    "files": [
      {
        "path": null,
        "fileName": "My test file",
        "contentType": "text/html",
        "url": "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/STORAGE_sessions/73/3b6113bc-f265-4662-8cc5-ea86f06cc74b/My%20test%20file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T114524Z&X-Amz-Expires=900&X-Amz-Signature=499367f6c6bff5be50686724475ac2fa6307b77b94fd1a25584c092fe74b0a58&X-Amz-SignedHeaders=host&x-id=PutObject",
        "fileUuid": "4ef1177b-f7c9-4434-be56-a559cec0cc18"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

2. End upload session
Once files are uploaded to the cloud server via the received URL, trigger file sync to IPFS and Crust.

🔻 cURL

curl --location --request POST "https://api.apillon.io/storage/:bucketUuid/upload/:sessionUuid/end" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"directSync\": true
}"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "b64b1c07-1a8a-4b05-9e3b-3c6a519d6ff7",
  "status": 200,
  "data": true
}
Enter fullscreen mode Exit fullscreen mode

3. Get bucket content
Next, get directories and files in the storage bucket. Note that items are paginated and can be filtered and ordered through query parameters.

🔻 cURL basic

curl --location --request GET "https://api.apillon.io/storage/:bucketUuid/content" \
--header "Authorization: Basic :credentials"
Enter fullscreen mode Exit fullscreen mode

🔻 cURL with params

curl --location --request GET "https://api.apillon.io/storage/:bucketUuid/content?orderBy=name&desc=false&limit=5&page=1" \
--header "Authorization: Basic :credentials"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
    "id": "c8c50b3b-91ff-42c7-b0af-f866ce23f18a",
    "status": 200,
    "data": {
        "items": [
            ...
            {
                "type": 1,
                "id": 11,
                "status": 5,
                "name": "My directory",
                "CID": null,
                "createTime": "2022-12-08T13:27:00.000Z",
                "updateTime": "2023-01-10T12:18:55.000Z",
                "contentType": null,
                "size": null,
                "parentDirectoryId": null,
                "fileUuid": null,
                "link": null
            },
            {
                "type": 2,
                "id": 397,
                "status": 5,
                "name": "My file.txt",
                "CID": "QmcG9r6Rdw9ZdJ4imGBWc6mi5VzWHQfkcLDMe2aP74eb42",
                "createTime": "2023-01-19T10:10:01.000Z",
                "updateTime": "2023-01-19T10:10:31.000Z",
                "contentType": "text/plain",
                "size": 68,
                "parentDirectoryId": null,
                "fileUuid": "0a775bfa-a0d0-4e0b-9a1e-e909e426bd11",
                "link": "https://ipfs.apillon.io/ipfs/QmcG9r6Rdw9ZdJ4imGBWc6mi5VzWHQfkcLDMe2aP74eb42"
            }
            ...
        ],
        "total": 10
    }
}
Enter fullscreen mode Exit fullscreen mode

4. Get file details
Lastly, get details of a specific file inside a storage bucket.

🔻 cURL

curl --location --request GET "https://api.apillon.io/storage/:bucketUuid/file/:id/detail" \
--header "Authorization: Basic :credentials"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "5be33c54-2cc9-46f4-8f50-debc98866810",
  "status": 200,
  "data": {
    "fileStatus": 4,
    "file": {
      "id": 397,
      "status": 5,
      "fileUuid": "0a775bfa-a0d0-4e0b-9a1e-e909e426bd11",
      "CID": "QmcG9r6Rdw9ZdJ4imGBWc6mi5VzWHQfkcLDMe2aP74eb42",
      "name": "My file.txt",
      "contentType": "text/plain",
      "size": 68,
      "fileStatus": 4,
      "downloadLink": "https://ipfs.apillon.io/ipfs/QmcG9r6Rdw9ZdJ4imGBWc6mi5VzWHQfkcLDMe2aP74eb42"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

That's it, your files should now be stored on Crust Network.

5. Delete file
To delete a file, you can mark it for deletion inside a storage bucket using id, fileUuid, or CID. The file will be completely deleted from the Apillon system and Apillon IPFS node after three months. Once a file is marked for deletion, it will not be renewed on Crust Network.

🔻 cURL

curl --location --request DELETE "https://api.apillon.io/storage/:bucketUuid/file/:id" \
--header "Authorization: Basic :credentials" \
--data-raw ""
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "bc92ff8d-05f2-4380-bb13-75a1b6b7f388",
  "status": 200,
  "data": {
    "id": 397,
    "status": 8,
    "fileUuid": "0a775bfa-a0d0-4e0b-9a1e-e909e426bd11",
    "CID": "QmcG9r6Rdw9ZdJ4imGBWc6mi5VzWHQfkcLDMe2aP74eb42",
    "name": "My file.txt",
    "contentType": "text/plain",
    "size": 68,
    "fileStatus": 4
  }
}
Enter fullscreen mode Exit fullscreen mode

Voila, you've made it through the whole process of uploading files to decentralized storage via Crust Network and Apillon API.

🔎 Dive into more details, parameters, metadata, and statuses of the Web3 Storage API and connect Crust Network's decentralized storage service to your website or app.

apillon-web3-storage-api-wiki

Web3 Hosting API

Apillon Web3 Hosting API connects to the Crust Network, where you can host your website in a decentralized way.

Before you start using the Web3 Hosting API, there are two things to keep in mind:

  • You should first create a website on the Apillon dashboard.
  • In all cURL examples, parameters with a colon as a prefix should be replaced with real values.

Website deployment process via Apillon Web3 Hosting API

Apillon Hosting API provides endpoints that can be used to implement CI/CD.

The website you host on the Crust Network is deployed as follows:

  1. Website files are uploaded to the Apillon cloud server.
  2. Request URLs for files upload.
  3. Files are uploaded to a cloud server.
  4. Trigger transfer to website.
  5. Deployment to staging or production environment.

Now, let's do it step by step using Apillon API.

How to use Apillon Web3 Hosting API

1. Get URLs for files upload
First, create file upload requests that return URLs for file upload.

🔻 cURL

curl --location --request POST "https://api.apillon.io/hosting/websites/:websiteUuid/upload" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"files\": [
        {
            \"fileName\": \"index.html\",
            \"contentType\": \"text/html\"
        },
        {
            \"fileName\": \"styles.css\",
            \"contentType\": \"text/css\",
            \"path\": \"assets/\"
        }

    ]

}"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "7dd011ec-20e2-4c28-b585-da6c6f7fce8d",
  "status": 201,
  "data": {
    "sessionUuid": "29ef6ca2-b171-440c-b934-db8aa88c3424",
    "files": [
      {
        "path": null,
        "fileName": "index.html",
        "contentType": "text/html",
        "url": "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/HOSTING_sessions/70/29ef6ca2-b171-440c-b934-db8aa88c3424/index.html?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T105030Z&X-Amz-Expires=900&X-Amz-Signature=187035d2307bc089101eff3abbdd7baa3e8691b4d5d3bafa5aebb87e589e8c0c&X-Amz-SignedHeaders=host&x-id=PutObject",
        "fileUuid": "e17436a1-5292-4380-ad91-eaac02a862b1"
      },
      {
        "path": "assets/",
        "fileName": "styles.css",
        "contentType": "text/css",
        "url": "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/HOSTING_sessions/70/29ef6ca2-b171-440c-b934-db8aa88c3424/assets/styles.css?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T105030Z&X-Amz-Expires=900&X-Amz-Signature=f91b03a951fe3f99291802306be3e79812ca64e39effbb7dea1c19bb7cd1e42b&X-Amz-SignedHeaders=host&x-id=PutObject",
        "fileUuid": "358c2942-4ced-421e-9a6f-edbf94c55dff"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

2. End upload session
Now, transfer files to the website storage bucket, which is used as a source for deployment to a staging (preview) environment.

🔻 cURL

curl --location --request POST "https://api.apillon.io/hosting/websites/:websiteUuid/upload/:sessionUuid/end" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"directSync\": true
}"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "b64b1c07-1a8a-4b05-9e3b-3c6a519d6ff7",
  "status": 200,
  "data": true
}
Enter fullscreen mode Exit fullscreen mode

3. Deploy website
Next, utilize endpoint to trigger website deployment into specific a environment.

🔻 cURL

curl --location --request POST "https://api.apillon.io/hosting/websites/:websiteUuid/deploy" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"environment\": 1
}"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "32eff81a-6b0b-4a92-a5cb-e5cebf6d6c28",
  "status": 200,
  "data": {
    "id": 51,
    "status": 5,
    "websiteId": 4,
    "bucketId": 62,
    "environment": 1,
    "deploymentStatus": 0,
    "cid": null,
    "size": null,
    "number": 11
  }
}
Enter fullscreen mode Exit fullscreen mode

4. Get deployment
Now, trigger endpoint to initiate deployment.

🔻 cURL

curl --location --request GET "https://api.apillon.io/hosting/websites/:websiteUuid/deployments/:deploymentId" \
--header "Authorization: Basic :credentials"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "2d7d1b0c-15b1-4816-9aec-857182c7b617",
  "status": 200,
  "data": {
    "id": 51,
    "status": 5,
    "bucketId": 62,
    "environment": 1,
    "deploymentStatus": 10,
    "cid": "QmY3KF4F6Ap5HbrwWpq8dTVaR65Cd674jYXKBayNynDASJ",
    "size": 289,
    "number": 11
  }
}
Enter fullscreen mode Exit fullscreen mode

5. Get website
Finally, get your website by triggering the endpoint to return basic website data, along with IPNS links.

🔻 cURL

curl --location --request GET "https://api.apillon.io/hosting/websites/:websiteUuid" \
--header "Authorization: Basic :credentials"
Enter fullscreen mode Exit fullscreen mode

🔻 Response

{
  "id": "0eb223ce-51c0-4a9b-96ce-331a1cd99603",
  "status": 200,
  "data": {
    "id": 4,
    "status": 5,
    "name": "My test page",
    "description": null,
    "domain": "",
    "bucketUuid": "57aef0fc-84cb-4564-9af2-0f7bfc0ef729",
    "ipnsStagingLink": "https://ipfs.apillon.io/ipns/k2k4r8p6fvcyq5qogaqdtvmqn5vyvyy3khut1llkrz13ls16ocp4gojx",
    "ipnsProductionLink": "https://ipfs.apillon.io/ipns/k2k4r8ng8nqexubrmbwnhsuu1d6n4ebgnxsbdcu9gxk8uv3l67098hge"
  }
}
Enter fullscreen mode Exit fullscreen mode

That's it, in just a few steps, you have upgraded your website's hosting to a decentralized level.

🔎 Dive into specifics of Web3 Hosting API and connect with Crust Network's decentralized storage to host your website or app.

apillon-web3-hosting-api-wiki

Web3 access the APIllon way

Apillon API provides straightforward connectivity to Polkadot parachain services while respecting the standard development workflow.

By accessing Web3 services via APIs, you can launch your Web3 project faster and with hardly anything to break since you control all the code.

Let us know how you find Apillon APIs and build away!

apillon-go-to-wiki-cta
apillon-proceed-to-dashboard-cta

This post was originally published on Apillon Medium.

Top comments (0)

Read next

samuel_udeh profile image

Managing Terraform State: Best Practices for DevOps

Samuel Udeh -

ishan_siddhartha profile image

Week 3 Done

Ishan Siddhartha -

hema_latha profile image

What is return data types ?

hema latha -

hema_latha profile image

why java is a platform Independent ?

hema latha -