9 min read
Overview
Creating a REST API add-on for the QuickNode Marketplace allows you to extend QuickNode's capabilities by adding custom REST endpoints. Developing QuickNode marketplace add-ons enables you to deploy and monetize your API on the QuickNode Marketplace, providing access to a vast community of developers. Once your add-on is approved, it will be featured on the QuickNode Marketplace, and you will receive support and promotion from the QuickNode team to help reach potential users and maximize the impact of your service.
In this guide, we will go through the steps to create your own REST API add-on, along with providing links to in-depth guides and resources on related topics.
What You Will Do
- Learn about developing and testing a REST API add-on for QuickNode Marketplace
- Learn the process of submitting your add-on to the QuickNode Marketplace, including preparation, approval, and monetization
What You Will Need
- A free QuickNode account
- Ngrok for testing (Optional, but recommended for local development)
Apply for a Developer Account on QuickNode
First, let's apply for a developer account to be able to create add-ons on QuickNode Marketplace. From your QuickNode dashboard, click the Switch to Partners tab on the left nav bar, and then complete the marketplace account application. Here’s a preview of the form:
Approval process for new marketplace partners may take up to 7 business days, however, in general, you can generally expect a response in 1-2 business days.
Building and Testing Your REST API Add-On
Creating a REST API add-on involves developing and testing your service to ensure it meets QuickNode's standards.
Step 1: Develop Your REST API Add-On
You can begin developing your REST API add-on from scratch, focusing on building the necessary endpoints for provisioning, health checks, and the REST API paths you wish to expose.
QuickNode offers starter codes that include provisioning and health check functionalities; however, these starter codes do not currently support REST API add-ons. We are actively working on adding REST API support to the starter codes, which will be available soon. For now, building your REST API add-on from scratch is the recommended approach.
During development, you need to implement the necessary endpoints for provisioning and health checks, and the REST API paths you wish to expose.
| Programming Language | Starter Code Repository |
|---|---|
| Python | QuickNode Marketplace Starter Code - Python |
| JavaScript | QuickNode Marketplace Starter Code - JavaScript |
| Ruby | QuickNode Marketplace Starter Code - Ruby |
| Go | QuickNode Marketplace Starter Code - Go |
| Ruby on Rails | QuickNode Marketplace Starter Code - Ruby on Rails |
Provisioning
Your add-on must include the following endpoints to manage its lifecycle:
| Endpoint | Description |
|---|---|
/provision | Used to provision a new instance of your add-on for a QuickNode user. |
/deprovision | Handles the removal of an add-on instance when a user decides to stop using your add-on. |
/deactivate_endpoint | Deactivates a specific endpoint associated with your add-on. |
/update | Allows for updating an existing provisioned add-on instance. |
Learn more about how provisioning works for Marketplace Partners
Health Check
Implement a health check endpoint (e.g., /healthcheck) that QuickNode can use to verify your service's availability.
Single Sign-On (SSO)
If your add-on includes an external dashboard, you might need to implement JWT-based SSO.
Step 2: Testing Your Add-On
Testing your REST API add-on is a critical step before submitting it to the QuickNode Marketplace. The qn-marketplace-cli tool is designed to help you test your add-on's functionality directly in your local development environment or on a server.
Although all the information on how to use this tool is available in detail in the GitHub repository, let's examine some of the information together.
Before moving on, ensure that your add-on is running before you begin testing. Use the appropriate host URL (e.g., http://localhost:3000 or your remote server URL) when configuring your tests.
Installing qn-marketplace-cli
To get started, install the qn-marketplace-cli on your machine by downloading a pre-built binary from the QuickNode GitHub repository. Alternatively, you can build it from source if preferred.
Testing Provisioning
Since your add-on must implement four provisioning endpoints to manage its lifecycle (/provision, /deprovision, /deactivate_endpoint, and /update), you can test these endpoints individually or all at once using the CLI tool.
After installing the qn-marketplace-cli tool, you may need to provide the correct path to execute it. For example:
go/bin/qn-marketplace-cli help
Alternatively, you can navigate to the directory where the CLI tool is located and run the command directly:
cd go/bin/
./qn-marketplace-cli help
The pudd command simulates the entire lifecycle of provisioning, updating, deactivating, and deprovisioning an endpoint for your add-on. Below is the command and an explanation of the flags you'll need to use:
./qn-marketplace-cli pudd \
--base-url=http://localhost:3000/provisioning \
--basic-auth=<your-auth-code> \
--chain=<selected-chain> \
--network=<selected-network> \
--plan=<your-plan-slug> \
--endpoint-url=<your-endpoint-url> \
--wss-url=<your-wss-url>
| Flag | Description |
|---|---|
--base-url | The base URL of the add-on's provisioning API. |
--basic-auth | The basic auth credentials for the add-on. Defaults to username = Aladdin and password = open sesame (default "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="). |
--chain | The chain to provision the add-on for (default "ethereum"). |
--endpoint-id | The endpoint ID to provision the add-on for (optional) (default "72b1201c-84fd-4244-ad21-f056a97f043d"). |
--endpoint-url | The endpoint URL to provision the add-on for (optional - defaults to an Ethereum mainnet endpoint) (default "https://long-late-firefly.quiknode.pro/4bb1e6b2dec8294938b6fdfdb7cf0cf70c4e97a2/"). |
--network | The network to provision the add-on for (default "mainnet"). |
--plan | The plan to provision the add-on for. (default "discover") |
--quicknode-id | The QuickNode ID to provision the add-on for (optional) (default "5f649496-0d0a-4637-9b4b-e96fbe19bcdd"). |
--wss-url | The WebSocket URL to provision the add-on for (optional - defaults to an Ethereum mainnet endpoint) (default "wss://long-late-firefly.quiknode.pro/4bb1e6b2dec8294938b6fdfdb7cf0cf70c4e97a2/"). |
If you need more information about any command or flag, the CLI provides built-in help options. You can access general help or specific help for individual commands as follows:
./qn-marketplace-cli help
./qn-marketplace-cli pudd --help
The qn-marketplace-cli allows you to test your add-on both locally and on a remote server. For local testing, commands can be run against a service hosted on localhost. For server testing, simply point the commands to your deployed service.
For example, if you are using our QuickNode Marketplace Starter Code - JavaScript, which is a sample add-on built with Node.js, you can use the following command to test provisioning locally. This assumes you have set the username and password to username and password respectively.
./qn-marketplace-cli pudd \
--base-url http://localhost:3030/provisioning \
--quicknode-id foobar \
--endpoint-id bazbaz \
--chain ethereum \
--network mainnet \
--basic-auth dXNlcm5hbWU6cGFzc3dvcmQ=
Testing REST API Endpoints
The CLI also supports testing REST API methods, allowing you to ensure that your REST API add-on functions correctly. Below is the command you'll need to use:
./qn-marketplace-cli rest \
--rest-url=http://localhost:3000/your-rest-path \
--rest-verb=POST \
--rest-body='{"key":"value"}' \
--basic-auth=<your-auth-code> \
--chain=ethereum \
--network=mainnet \
--plan=<your-plan-slug> \
--quicknode-id=<your-quicknode-id> \
--endpoint-id=<your-endpoint-id> \
--endpoint-url=<your-endpoint-url>\
--wss-url=<your-wss-url>
Apart from the flags mentioned in the previous example, the description of the flags specific to the REST command is as follows:
| Flag | Description |
|---|---|
--rest-body | The REST request body to be used in the REST call. |
--rest-url | The URL to make the REST calls to. |
--rest-verb | The REST HTTP method or verb to use (e.g., GET or POST). |
All Provisioning and Update APIs must be secured with HTTP Basic Authentication. You'll receive credentials during the Marketplace onboarding process, accessible in your add-on's security tab. For local testing, you can set your own username and password, and generate the Basic Authentication value using Base64.
For Base64 encoding, you can create your value in username:password format using one of the websites like this.
Testing with ngrok
For local testing, ngrok can be a useful tool to expose your local service to the internet via a secure tunnel. This allows you to simulate real-world conditions when testing provisioning, update, and de-provisioning actions.
To set up ngrok, install it by running the command for your operating system:
- Mac
- Windows
- Linux
brew install ngrok/ngrok/ngrok
choco install ngrok
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list && sudo apt update && sudo apt install ngrok
Once ngrok is installed, make sure your local server is running on port 3000 (or your desired port). Then, run ngrok to create a secure URL that points to your local service:
ngrok http 3000
This will provide a public URL (e.g., https://abcd1234.ngrok.io) that you can use to test your add-on with qn-marketplace-cli, as if it were deployed on a live server.
Step 3: Refer to Related Guides
As you develop and test your add-on, you may need to reference additional guidelines and resources:
It is crucial to thoroughly test your add-on before submitting it to the QuickNode Marketplace. This involves running the PUDD command to test all provisioning endpoints, verifying the healthcheck, and testing all REST paths your add-on provides for the chains you plan to support.
Rest assured, if anything requires further attention, the QuickNode team will provide feedback during the internal review.
Adding Your REST API Add-On to the Marketplace
Once your REST API add-on is developed and tested, the next step is to submit it to the QuickNode Marketplace. This section covers the process of creating your add-on in the marketplace, including filling out the required forms and submitting your add-on for approval.
Step 1: Create Your Add-On in the Marketplace
To get started, log in to your QuickNode dashboard and navigate to the Switch to Partners tab. Here, you will begin the process of adding your REST API add-on to the marketplace.
Step 2: Add-On Form - Basic
You will need to provide detailed information about your add-on, which is organized into several sections:
Basic Information
- Add-on Name and Description: Provide a name and description for your add-on.
- Icon and Screenshots: Upload visuals that represent your add-on. Refer to the icon guidelines and screenshot guidelines for best practices
- Supported Chains and Networks: List the chains and networks that your add-on supports. (e.g., Ethereum Mainnet)
- Provision Related URLs: Provide the URLs for provisioning, deprovisioning, etc. (e.g., https://api.yourservice.com/provision)
- JWT Secret: (If applicable) Generate and provide a JWT secret (You may use
openssl rand -hex 32command to generate a random JWT secret code.). - Support Email and URL: Provide contact information for customer support.
- Alert Email: Enter an email address for receiving alerts about your add-on's status.
- Using Customers' QuickNode API Endpoints: Specify if your add-on will interact with QuickNode API endpoints.
Add-On Type
- Select Add-On Type: Choose REST API.
- Add REST Paths: Define the REST paths your add-on will expose, including:
- HTTP Method (e.g.,
GET,POST) - REST API URL (e.g., https://api.yourservice.com/prices)
- Health Check URL (e.g., https://api.yourservice.com/healthcheck)
- Documentation URL (e.g., https://yourservice.com/docs/api)
- Description (e.g., Fetches the latest cryptocurrency prices for supported tokens.)
- Sample Request Body (e.g.,
{"token": "ETH", "currency": "USD"})
Step 3: Add-On Form - Features
Highlight the key features of your add-on that users will benefit from. (e.g., Real-time price updates, support for multiple cryptocurrencies).
Step 4: Add-On Form - Plans
List the pricing plans you will offer to QuickNode users. (e.g., Free tier with limited requests, Premium tier with unlimited access).
Step 5: Add-On Form - Test Access
Once you've completed the submission form, request test access from the QuickNode team. They will review your add-on and, if everything is in order, grant you access to test your add-on within the QuickNode environment.
Marketplace Add-on Approval Criteria
QuickNode approves add-ons that excel in one or more of the following criteria:
- Scalability: The add-on demonstrates robust performance under QuickNode's high-volume traffic demands.
- Specialized Functionality: The add-on offers unique, purpose-built features that address specific blockchain development needs.
- Innovation: The add-on introduces groundbreaking capabilities or novel approaches to blockchain interaction.
- Core Infrastructure: The add-on serves as an essential component in our customers' blockchain development stack. Add-ons meeting these standards not only enhance QuickNode's ecosystem but also deliver significant value to our users.
If your add-on meets one or more of these requirements, there is a high likelihood we will reach out to learn more and fast-track your add-on.
Going Live
After successful testing and approval, you’ll get placement in app on the check out page, the add-ons tab for endpoints and the public website. You will receive placement on the QuickNode MarketPlace and additional promotional support to help reach potential customers.
Wrap Up
Congratulations on creating and submitting your REST API add-on to the QuickNode Marketplace!
If you have any questions, feel free to use our dedicated channel on Discord or provide feedback using the form below. Stay up to date with the latest by following us on Twitter and our Telegram announcement channel.
We ❤️ Feedback!
Let us know if you have any feedback or requests for new topics. We'd love to hear from you.