NFTRainbow API使用指南
NFTRainbow API作为以gin框架为基础的NFT服务，为无web3技术栈的web2用户在conflux平台发布自己的NFT提供了方便。本文将从web2用户的角度出发，对如何使用NFTRainbow API做出详细说明。
准备工作
从git仓库pull代码到本地
git clone https://github.com/nft-rainbow/rainbow-api创建数据存储路径
sudo mkdir -p /opt/storages
sudo mkdir -p /opt/storages/file
sudo mkdir -p /opt/storages/metadata创建config.yaml
cp config.sample.yaml config.yaml在mysql服务中创建相应数据库，并根据本地mysql配置与fluent钱包中的账号配置修改config.yaml中相应的字段，包括mysql, testmysql, defaultAccounts, easyNft.
运行NFTRainbow API 服务
go run main.go鉴权
NFTRainbow API是基于JWT来实现用户权限的鉴定的.
获取JWT
在通过Rainbow Console获取到app_id与app_secret后，可以通过调用Login API来获得对应的JWT.具体的有：
curl --request POST \
--url https://api.nftrainbow.xyz/v1/login \
--header 'Content-Type: application/json' \
--data `{
"app_id": "qUUcdueA",
"app_secret": "zGCaP8kAFEmwanqo"
}响应结果如下：
{
"code": 0,
"data": {
"expire": "2022-08-28T16:50:05.7704294+08:00",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjE2NzY2MDUsImlkIjoyLCJvcmlnX2lhdCI6MTY1OTA4NDYwNX0.vEXdWizTUcTtUjHzrJqrOjCLe5PmnR9sHuZqqGICLqw"
}
}注意的是，在一个小时的有效时限内, 用户可以利用该JWT去调用Open APIs, 包括Files, Metadata, NFT和contract.
刷新JWT
一旦超出了一个小时, 在五个小时的有效时限内, 用户可以利用该JWT去调用refresh_token，实现JWT的刷新功能. 具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/refresh_token \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'响应结果如下：
{
"code": 0,
"data": {
"expire": "2022-08-28T16:50:55.8437443+08:00",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjE2NzY2NTUsImlkIjoyLCJvcmlnX2lhdCI6MTY1OTA4NDY1NX0.8k3JrmgmD20EfEJVGWbZ3gQYH_-Bt80miQXcQscq3MY"
}
}铸造NFT流程
铸造NFT的流程如下图所示. 可以看到, NFTRainbow API为用户提供了三种铸造方式. 为了实现传统方式铸造NFT, 在部署合约成功获得合约地址的基础上, 用户需要上传文件, 并用获得的file_url来创建Metadata从而获取对应的metadata_uri. 而上传文件来铸造NFT与创建Metadata来铸造NFT的方式则为用户提供了更加开放与快捷的方式去实现NFT铸造. 在本节中将为各个接口如何实现进行说明. 
上传文件
为了实现传统铸造NFT的功能, 用户需要获得metadata_uri. 而为了获取metadata_uri, 用户需要上传文件来获取相应的file_url. 具体的有：
curl --request POST \
--url https://api.nftrainbow.xyz/v1/files \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: multipart/form-data' \
--header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
--form file=相应的响应为:
{
"code": 0,
"data": {
"file_url": "http://localhost:8080/assets/file/2/nft/fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b.jpeg",
"file_size": 11295,
"file_type": "jpeg",
"file_name": "fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b"
}
}创建Metadata
在获得了file_url后, 需要调用create_metadata去获得metadata_uri. 具体的有:
curl --request POST
--url https://api.nftrainbow.xyz/v1/metadata/ \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '{
"attributes": [
{
"attribute_name": "mouse",
"display_type": "test hey hey",
"trait_type": "big",
"value": "big"
}
],
"description": "this is a test metadata",
"external_link": "https://www.google.com/search",
"file": "https://www.google.com/search",
"name": "test"
}相应的响应为:
{
"code": 0,
"data": {
"metadata_uri": "http://localhost:8080/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
}
}部署合约
目前NFTRainbow API通过NFTFactory合约来进行合约部署。该合约在测试网的合约地址为cfxtest:acdh1unre2bsdtwfuv0enu7tuychw0sm9afxe9f8b0，该合约的对应代码可以参考项目的git仓库.
用户若想要调用该合约去部署自己的ERC721合约或ERC1155合约, 需要使得自己的账户拥有对应的角色，因此需要NFTFactory合约的admin调用合约方法对账户进行赋权。在用户账户拥有了相应的角色后，可以调用NFTRainbow API来进行合约的部署。
NFTRinbow API为用户提供了相应的API, 帮助用户去创建合约, 从而获得合约地址address. 为了部署合约, 可以调用deploy_contract API. 具体的有:
curl --request POST \
--url https://api.nftrainbow.xyz/v1/contracts \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '{
"chain": "conflux_test",
"name": "NFT-name",
"symbol": "ENFT",
"owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
"type": "erc721",
"base_uri": ""
}'注意的是, type必须为erc721或是erc1155(区分大小写).
相应的响应为:
{
"code": 0,
"data": {
"id": 6,
"created_at": "2022-07-29T16:52:44.596+08:00",
"updated_at": "2022-07-29T16:52:44.596+08:00",
"deleted_at": null,
"app_id": 2,
"chain_type": 1,
"chain_id": 1,
"address": "",
"owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
"type": 1,
"base_uri": "",
"name": "NFT-name",
"symbol": "ENFT",
"hash": "",
"tx_id": 14,
"status": 0
}
}在获得上述响应后，可以在conflux scan中查找部署的合约地址。步骤如下：
- 根据账户地址查找交易列表
- 根据交易哈希查找对应交易
- 在对应的交易信息页面中根据事件日志获取合约地址
如下图所示, 红框中的地址是部署后的合约地址
传统方式铸造NFT
在通过创建Metadata与部署合约获得metadata_uri与contract_address后, 可以调用合约中的方法去铸造NFT. NFTRainbow API简化了用户与合约间的交互流程, 用户可以直接调用相应的API去实现与合约的交互. 传统方式铸造NFT, 具体的有:
curl --request POST \
--url https://api.nftrainbow.xyz/v1/mints \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '{
"chain": "conflux_test",
"token_id": "",
"mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"contract_address": "cfxtest:acgat1yux2rk0xmk2s8ceferyprgm0u1hetj0w72yf",
"metadata_uri": "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png"
}'相应的响应为:
{
"chain": "conflux_test",
"name": "123",
"description": "123",
"mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"contract_address": "cfxtest:acf8m2gzrv8pnfsjbne2d28m4h2ycj569uupgys473",
"metadata_uri": "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png"
}上传文件来铸造NFT
除了传统方式铸造NFT外, NFTRainbow API还为用户提供了更加简捷的方法来铸造NFT. 这包括上传文件来铸造NFT与创建Metadata来铸造NFT. 上传文件忽略了上传文件与创建Metadata两步, 用户可以直接调用API来实现NFT的铸造. 具体的有:
curl --request POST \
--url https://api.nftrainbow.xyz/v1/mints/files \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: multipart/form-data' \
--header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
--form file= \
--form chain= 'conflux_test' \
--form description= 'throll description' \
--form mint_to_address= 'cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk' \
--form name= 'throll'相应的响应为:
{
"code": 0,
"data": {
"id": 10,
"created_at": "2022-07-29T16:53:46.867+08:00",
"updated_at": "2022-07-29T16:53:46.867+08:00",
"deleted_at": null,
"app_id": 2,
"chain_type": 1,
"chain_id": 1,
"contract": "cfxtest:acgraybn1g1upesed09g96vxev79sdhmxjmz7bxzyy",
"mint_to": "cfxtest:acdh1unre2bsdtwfuv0enu7tuychw0sm9afxe9f8b0",
"token_uri": "http://localhost:8080/assets/metadata/0/nft/f7393d22ab69bed8828a5cea068398a5f14701304ef5b9a3840bc018d4ed78b9.json",
"token_id": 0,
"amount": 1,
"status": 0,
"hash": "",
"tx_id": 16,
"error": ""
}
}创建Metadata来铸造NFT
创建Metadata来铸造NFT忽略了创建Metada, 用户只需要提供由上传文件生成的file_url, 就可以实现NFT的铸造功能. 具体的有：
curl --request POST \
--url https://api.nftrainbow.xyz/mints/urls \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '{
"chain": "conflux_test",
"name": "123",
"description": "123",
"mint_to_address": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"file_url": "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png"
}'相应的响应为:
{
"code": 0,
"data": {
"id": 11,
"created_at": "2022-07-29T16:54:01.745+08:00",
"updated_at": "2022-07-29T16:54:01.745+08:00",
"deleted_at": null,
"app_id": 2,
"chain_type": 1,
"chain_id": 1,
"contract": "cfxtest:acgraybn1g1upesed09g96vxev79sdhmxjmz7bxzyy",
"mint_to": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"token_uri": "http://localhost:8080/assets/metadata/0/nft/c3e31daa28ab54f6e3cfd650021373411b06a0692d4c4f01ae20be5fcf5cf70d.json",
"token_id": 0,
"amount": 1,
"status": 0,
"hash": "",
"tx_id": 17,
"error": ""
}
}至此, 已实现NFT的铸造功能. 可以通过在conflux scan查找用户地址，在数字藏品资产页面下来查看生成的NFT. 
为合约设置sponsor
在调用合约的方法去铸造NFT时, 需要花费相应的代币(相当于花钱). 这些代币可以在fluent钱包当中可以查询到. 若用户没有足够的代币, 则没法去铸造NFT. 所幸的是, conflux链中存在sponsor功能. 该功能可以为合约设置一个sponsor, 在该合约白名单当中的用户, 可以免费调用该合约的方法, 而不需要支付相应的代币. 这些代币将由sponsor来代付.
NFTRainbow API提供了相应的API, 帮助用户为部署的合约提供相应的sponsor. 具体的有:
curl --request POST \
--url https://api.nftrainbow.xyz/v1/contracts/:address/sponsor \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为:
{
"code": 0,
"data": "success"
}需要注意的是, 该功能目前只能在conflux的测试网实现.
查询功能
NFTRainbow API为用户提供了相应的信息查询功能.
查询文件列表
在上传完文件后, 用户可以调用query_fileList API去实现文件列表的查询功能.具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/files \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"count": 2,
"items": [
{
"file_url": "http://localhost:8080/assets/file/2/nft/fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b.jpeg",
"file_size": 11295,
"file_type": "jpeg",
"file_name": "fa6f733c258e3a0f364aeb18198c9e2bae2e2c91bee4d38a1c88fb9cc8a71a1b"
},
{
"file_url": "http://localhost:8080/assets/file/2/nft/06edf22f414234ea59c949104a054ca4af27cd71e87170d99401b50d15651cdc.jpeg",
"file_size": 11295,
"file_type": "jpeg",
"file_name": "06edf22f414234ea59c949104a054ca4af27cd71e87170d99401b50d15651cdc"
}
]
}
}根据metadata_id查询metadata
在创建metadata后, 用户可以提供metadata_id调用query_metadata API去实现查询metadata的功能. 具体的有:
curl --request GET \
--url https://localhost:8080/v1/metadata/:metadata_id \
--header 'Authorization: 'Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"name": "test",
"description": "this is a test metadata",
"external_link": "https://www.google.com/search",
"image": "http://localhost:8080/assets/file/3/nft/02c95850aacd060da60f6fe500ff5bb06d67663682bef8fd490dedf0a0e7b2a7.png",
"attributes": [
{
"attribute_name": "eyes",
"trait_type": "test trait",
"display_type": "",
"value": "big"
},
{
"attribute_name": "mouse",
"trait_type": "test hey hey",
"display_type": "",
"value": "big"
}
]
}
}值得注意的是, metadata_id可以通过传回的metadata_uri获得. 如
http://localhost:8080/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json
该metadata的id为：
f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490
查询metadata列表
在创建metadata后, 用户可以调用query_metadata_list API去实现查询metadata列表的功能. 具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/metadata/ \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"metadata": {
"name": "test",
"description": "this is a test metadata",
"external_link": "https://www.google.com/search",
"image": "http://localhost:8080/assets/file/3/nft/02c95850aacd060da60f6fe500ff5bb06d67663682bef8fd490dedf0a0e7b2a7.png",
"attributes": [
{
"attribute_name": "eyes",
"trait_type": "test trait",
"display_type": "",
"value": "big"
},
{
"attribute_name": "mouse",
"trait_type": "test hey hey",
"display_type": "",
"value": "big"
}
]
},
"uri": "http://localhost:8080/assets/metadata/2/nft/f35c25ced3f537e8850a377c01d22aa7507069270054d12587ddbe5fc47ec490.json"
}
]
}
}查询合约列表
在部署完合约后, 用户可以通过list_contracts API来获取合约列表. 具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/contracts \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"id": 6,
"created_at": "2022-07-29T16:52:44.596+08:00",
"updated_at": "2022-07-29T16:53:10.282+08:00",
"deleted_at": null,
"app_id": 2,
"chain_type": 1,
"chain_id": 1,
"address": "",
"owner_address": "cfxtest:aatk708nbb7573bkwumsu00h0r1rtkcdz2chwhttzk",
"type": 1,
"base_uri": "",
"name": "NFT-name",
"symbol": "ENFT",
"hash": "",
"tx_id": 14,
"status": 2
}
]
}
}根据合约地址查询sponsor信息
在为合约设置完sponsor后, 用户可以通过get_contract_sponsor API来获取该sponsor的信息. 具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/contracts/:address/sponsor \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"gas_sponsor": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"gas_sponsor_balance": 10000000000000000000,
"collateral_sponsor": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"collateral_sponsor_balance": 100000000000000000000,
"is_all_white_listed": true,
"gas_upper_bound": 5000000000000000
}
}查询NFT列表
在铸造完NFT后, 用户可以通过list_mints API来获取铸造的NFT的列表. 具体的有:
curl --request GET \
--url https://api.nftrainbow.xyz/v1/mints \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json'相应的响应为：
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"id": 12,
"created_at": "2022-07-29T21:32:54.006+08:00",
"updated_at": "2022-07-29T21:32:54.006+08:00",
"deleted_at": null,
"app_id": 2,
"chain_type": 1,
"chain_id": 1,
"contract": "cfxtest:acf8m2gzrv8pnfsjbne2d28m4h2ycj569uupgys473",
"mint_to": "cfxtest:aasr1hmezez1wepvh8ew8sk9p40khhhj1ymxwmpaf0",
"token_uri": "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png",
"token_id": 4514651488,
"amount": 1,
"status": 0,
"hash": "",
"tx_id": 27,
"error": ""
}
]
}
}