Quick Start: Build Your First API
Let's build an API to manage stocks in a portfolio. We'll then make the API publicly available for any user to try and give feedback.
After you log in, we need to create a project. Click on the
plus icon and enter the project name & description on form on the the right side. When the project is created,
you can then create Paths, Resources and Types. For now, do not enter anything in the OpenAPI
which is used for initializing a project from a OpenAPI doc.
Create StockWhiz Project
Let's Build this API
We would like to have the following API:
| 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} |
We need a PATH for the collection of portfolios, then for each portfolio, we need a PATH for the sub-collection of stocks in a portfolio. So let's build a PATH fast by using a feature that takes a JSON object of a Portfolio and builds the Resource on the fly.
Click on the Paths menu in the left navigation, add the Path name and description. Let's skip Actions for now. We will select to Quick Create a Resource from the JSON object, provide the name of the Resource, then provide the JSON object of a portfolio and auto-generate a Portfolio Resource. This is a powerful feature to make prototyping very fast. After the Path is created, you can go to the Resource and make any changes to the properties of a Resource.
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 resources, a Porfolio resource was created. And, look under types, you'll see a type called Owner because automatically that Owner 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 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.