first-steps-with-request-api.md

description
This API Is currently in Beta, its specification may change in the future.

First steps with Request API

Getting Started with the Request API

Please note, if you would like to run a completely decentralised version of the Request network you can deploy your own node and interact with the network using the Request Client.​‌

The Request API is a REST API that enables you to create Requests, list Requests, and find a specific Request by its ID. Its purpose is to simplify interaction with the Request Protocol, abstracting all Blockchain-related aspects.‌‌

It is currently an alpha version, running on the Rinkeby Ethereum test network. It should not be used for production yet. Please check our roadmap to know more about our Protocol release to the Ethereum Mainnet.‌‌

Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and Bearer authentication.‌‌

Before using the API you MUST create an account here, and retrieve your API Key.‌‌

API Specs and Structure

You can view the full API spec here.‌‌

API Requests

To construct a REST API request, combine these components:

Component	Description
HTTP method	​ GET. Requests data from a resource. POST. Submits data to a resource to process.
API URL	​ Mainnet. https://api.request.network
URI Path	The resource to query, submit data to, update, or delete. For example, requests/${requestId}
​Query Parameters​	Optional. Controls which data appears in the response. Use to filter, limit the size of, and sort the data in an API response.
HTTP Request Headers	Includes the Authorization header with the access token. See the authorization section for more details.
JSON request body	Required for some endpoints, and details in the specs.

## Authentication

The Request API uses API keys to authenticate requests. You can view and manage your API keys using your Request Account.‌‌

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.‌‌

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.‌‌

HTTP Status Code Summary

Status Code	Summary
200 - OK	Everything worked as expected.
401 - Unauthorized	No valid API key provided.
403 - Forbidden	You cannot access this resource.
404 - Not Found	The requested resource doesn't exist.

‌

Errors

The Request API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: The 200 code indicates a successful request. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication issue, etc.).‌‌

Pagination

When fetching multiple Requests you will need to utilize cursor-based pagination via the skip and take parameters. Both parameters take an integer value and return a list of Requests ordered by the Request ID. The skip parameter bypasses a specified number of search results. The take parameter specifies the number of search results to return. Both of these parameters are optional, the defaults can be found here.‌

As an example, if you wanted to retrieve the first 50 Requests, skip would equal 0, and the takevalue would be 50. If you then wanted to retrieve the subsequent 50 Requests skip would equal 50, and takewould equal 50.‌

Basic Usage

Here is a basic example of creating a Request using the API via curl. Here, we are creating a basic BTC request.

curl -H "Authorization: [API-KEY]" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"currency": "BTC","expectedAmount": "100000000", "payment": { "type": "bitcoin-testnet", "value": "mqdT2zrDfr6kp69hHLBM8CKLMtRzRbT2o9" }}' \ 
     https://api.request.network/requests

Don't forget, you can get your API key from your Request Dashboard.‌‌

Examples

Creating an Invoice

To create an invoice, you must create a basic Request object which outlines some information about the Request such as the receiving payment address, which payment network is being used, the currency and the amount expected. You can retrieve individual requests as well as list all requests. Requests are identified by a unique UUID.‌‌

{% embed url="https://runkit.com/adamdowson/create-a-request/5.0.0" %}

You will notice that the API returns both an _id and and a requestId, which is empty at first. This is to speed up the response time, as the requestId will only get computed when persisted on the blockchain. You can get the requestId by fetching the invoice data a few minutes after you've created it, using the _id field. This should be removed in a next release.

Fetching an Invoice

All invoices have a unique ID, with this ID you can retrieve all the details of an invoice that has previously been created. By supplying the ID that was returned when creating the invoice you can query the endpoint as seen below, the API will then return the corresponding invoice information.‌

{% embed url="https://runkit.com/adamdowson/find-a-request/5.0.0" %}