Quick Start: Build Your First API
Most prototyping tools are very limited, you add a path URL, hard code a response and move on to next path, and so on. If you need to share this API for feedback, you would typically package it up and send to someone who has the tool. It does not really feel like using an API, it's simply getting a canned response to some simple URL paths. To build your own prototype requires developer skills of web servers, coding and databases and typically the pain is not worth the gain.
With RestPoint, you specify a Path and the Resource Type to use for that path. The big difference is this meta data is passed to the RestPoint backend service where a real API service and database is auto-generated and deployed in the cloud. There is no hard coded data, you send CRUD requests to your API just like the final API. This API looks and feels like the final API, because it actually is a real deployed API backend. And sharing is easy, the API is available online, you just need an API key that is also auto-generated for users.
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:37b6886d47aa49be8bbaa8a04ccffe3e https://api.restpoint.io/stockpicker-beta1/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.