Quick Start: Build Your First API

With RestPoint, you need to understand only a couple of concepts:

Let's build an example API to manage stocks in a portfolio. We'll then make the API publicly available for any user to try and give feedback.

Step 1: Create a Project

After you log in, we first create a project. Click on the "Create" button with plus icon, enter the project name & description on form on the the right side. When the project is created, you will see a Sandbox and Production section. We will first create Paths in our Sandbox, when we want to share with external users, we will deploy paths in an endpoint.

Create Project StockWhiz

Let's Build this API

We would like to have the following API for managing portfolios and stocks in portfolios:

POST	/portfolios
GET	/portfolios
GET	/portfolios/{id}
PUT	/portfolios/{id}
DELETE	/portfolios/{id}
POST	/portfolios/{id}/stocks
GET	/portfolios/{id}/stocks
GET	/portfolios/{id}/stocks/{id}
PUT	/portfolios/{id}/stocks/{id}
DELETE	/portfolios/{id}/stocks/{id}

Step 2: Design the first Path: /portfolios

We next will create a PATH for the collection of portfolios, called /portfolios. The data returned for this path is defined by a Resource Type. We just created our project, so we don't have a Resource Type to specify, so we have two choices, go to Resource Types and create/configure the properties of a Resource Type or use a RestPoint feature where you specify the JSON of a Portfolio and we'll auto-create the Resource Type for you based on the JSON (we find this feature much faster when prototyping).

Click on the Paths menu in the left navigation, add the Path name and description. Let's skip Actions and Response for now and use defaults. We will select "Create Resource Type from JSON", enter the name "Portfolio" for the Resource Type , then provide the JSON object of a portfolio and auto-generate a Portfolio Resource Type. After the Path is created, you can go to the Resource Type and make any changes to the properties of a Resource Type.

Create Portfolios Path

When you click on Add Path, a portfolios collection will be created and appear in the menu under Paths on the left. On the right, you'll see the list of portfolios, which now has the first item in the list that you specified on the create.

You'll also note under Resource Types, a Resource Type was created. And, look under Data Types, you'll see a Data Type called Owner because automatically that Owner Data Type was created from the JSON object of the portfolio.

After Portfolios Path created

Add Another Portfolio to Collection

Now that you have a Portfolios collection, you can add another Portfolio by adding the JSON in the text area and clicking Add Data. You can click Add Data with the text area empty to see a default item created with empty data or add a properly formatted JSON object of the data. Then you can change any of the fields in the text area by clicking edit and save.

Add Item to Path

Add Path for Stocks in a Portfolio

We need to have stocks in a portfolio, so let's add a stocks collection in portfolios, i.e. portfolios/{id}/stocks. We can create the Path the same way we did for portfolios with the addition of a portfolio id. Let's quick create Stock Resource Type by providing the JSON object for a stock. So click on Paths on the left navigation and choose Create.

Add Path for Stocks in a Portfolio

After the stock is added, you'll see the form to add more stocks to Portfolios.

Add Path for Stocks in a Portfolio

On the left navigation, you'll see the Path porfolios/{id}/stocks. Click on this Path, you'll see a select of the portfolio Paths containing stocks, select a one of the portfolio Paths to view the stocks in that portfolio.

Add Path for Stocks in a Portfolio

Let's Now Show our API to the World

Now that you have the portfolios and stocks collections created in your Sandbox, with data, you can now deploy those Paths to "simulated" Production by creating Endpoints and giving your external users access keys to connect to your Endpoints.

To create an endpoint, see under Production, click on Endpoints and then configure the panel on the right. Click on the Path names and click create.

Create Endpoint

You'll see all the information for the Endpoint with the URL at the top of page. You can instantly send requestions to your new Endpoint, a curl command is provided, or use PostMan/Insomnia, etc. to send CRUD requests to your Endpoint.

Endpoint Created

Further down on the Endpoint screen, you will see the endpoint keys. You will give an access key to your external users to send API requests, such as the following using the full access key:

curl -H "x-endpoint-key:fff089056d6144fc9530c557937af63e" https://api.restpoint.io/api/portfolios

There are four types of Endpoint keys, :

Full Access: users can read / write all collections

Read Only: users can read all collections

Create Only: users can only create data in collections, but can't read.

Me Only: users can only see data that they created, requires the users to authenticate to Google and pass the Bearer token

Share Your Endpoint

Click share on the Endpoint so anyone can find your shared Endpoints by searching on your user name on Shared Endpoints

Note the Endpoint is completely separate from your Sandbox, including the data is separate as well. If you make changes, you can deploy a new Endpoint to Production to keep previous verisons still available.

View Endpoint API's

You can view your Endpoint API's using Swagger UI or ReDoc. Simply copy the URL to your browser, note the Endpoint key provided by default is full access.