Decoo Wiki

Basics#

Decoo provides HTTP API to facilitate Decoo service usage. Under the One Cloud, Multiple Endpoints architecture, both Decoo Cloud and Endpoint are deployed with HTTP API to provide different types of services, with different authentication mechanisms.

Specifically,

Decoo Cloud provides all APIs except for file upload APIs like pinFile and pinByHash, using API Key for authentication.
Endpoint provides file upload APIs like pinFile and pinByHash, using OAuth2-like mechanisms for access authorization and authentication.

Decoo Cloud#

API Key#

API Keys are used to access Decoo Cloud API. When registering an account, an API Key is automatically generated. User could login in and check their API Key at panel -> API -> API JWT.

Each API Key is actually a JWT token which acts on behalf of the user when accessing Decoo API. Users should keep it private and never share it with others.

Accessing API#

The base url of Decoo Cloud API is: https://api.decoo.io

To authenticate with this endpoint, you need to include your API Key as an Authorization header for all your API requests in the following format:

"Authorization": "Bearer <YOUR_API_KEY>"

You can use following curl request to test your API Key against the endpoint:

curl -X GET "https://api.decoo.io/ping" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

On success, it should return with 200 and the following body:

{
  "Success": true
}

If token is invalid, it should return following body:

{
  "Code": 401,
  "Message": "Invalid token"
}

Endpoint#

Endpoint List#

Client could request Decoo Cloud API to get Endpoint list:

curl -X GET "https://api.decoo.io/endpoint/list" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

It should return results like below:

 [
   {
     "id": 1,
     "name": "Hong Kong",
     "apiHost": "https://api-hk.decoo.io"
   },
   ...
]

Access Token#

Endpoint use Access Token to authenticate user's API requests. Access Tokens are issued and verified by Decoo Cloud. The process flow is:

Client requests Access Token via Decoo Cloud API
Client calls Endpoint API, with the requested Access Token in request header
Endpoint calls Decoo Cloud API to verify the passed Access Token. If the token is valid, authenticate passes; otherwise, authenticate fails and 401 error will be returned to Client.

Besides, Access Token expires in 2 hours. Client should request a new Access Token if old ones expire.

To request Access Token：

curl -X GET "https://api.decoo.io/oauth/accessToken" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Digital Signature#

When calling Endpoint's pinFile or pinByHash API, user need attach a digital signature as API calling proof. The digital signature is generated by encrypting file CID with user's RSA private key, and will be verified by Decoo Cloud using user's RSA public key.

RSA Keys#

RSA Keys are automatically generated when registering accounts. User could login and check it at panel -> API -> Verification Key.

Calculating file CID#

There are mutltiple approaches to get a file's IPFS CID. Normally, the suggested way is to install IPFS Desktop locally, and using its /api/v0/add HTTP API to get a local file's CID (Note: When calling this API, it's suggested to set only-hash parameter value as true).

If you're building client App using JavaScript, a better suggestion is to use ipfs-core, which provides a lighter and more friendly approach to get file's CID. Actually, Decoo Client SDK uses this approach to get file CID.

Generating Digital Signature#

If using JavaScript, user could refer to pinFile of Decoo SDK about how to generate digital signature using user RSA private key and file CID.

For other commonly used programming languages, sample codes are like below:

Java

/**
 <dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
  </dependency>
 */

import org.apache.commons.codec.binary.Base64;
import javax.crypto.Cipher;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;

public class SecretGeneratorSample {
    private static final String CHARSET = "UTF-8";

    private static final String RSA_ALGORITHM = "RSA";

    private static final int KEY_SIZE = 1024;

    public static String generateSecret(String cid, String key) throws Exception {
        PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(key.getBytes(CHARSET)));
        KeyFactory keyFactory = KeyFactory.getInstance(RSA_ALGORITHM);
        PrivateKey privateKey = keyFactory.generatePrivate(pkcs8KeySpec);
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.ENCRYPT_MODE, privateKey);
        return new String(Base64.encodeBase64(cipher.doFinal(cid.getBytes(CHARSET))), CHARSET);
    }
}

Accessing API#

User must have a valid Access Token to access Endpoint API. Besides, to access file upload APIs like pinFile and pinByHash, a digital signature based on user RSA private key and file CID is also required.

As an example, user could use curl command below to access a Endpoint's pinFile API:

curl -X POST "https://api-hk.decoo.io/pinning/pinFile" \
  -H "UserAccessToken: <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@<YOUR_FILE_PATH>" \
  -F 'decooMetadata="{\"name\": \"My File\"}"' \
  -F "cid=<YOUR_FILE_CID>" \
  -F "secret=<YOUR_DIGITAL_SIGNATURE>"

Client SDK#

As mentioned above, Decoo provides a JavaScript version Client SDK, with the out of box implementation of functionalities like connecting to Endpoint, requesting Access Token, generating digital signature, etc. Users could use it to ease access Endpoint APIs.

The SDK could be used in both NodeJS and Browser environment. Please refer to the SDK for detailed usage.