Quick Start: Build Your First API
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 "+" button beside the Choose Project select box,
enter the project name & description on form on the the right side. Click the Add Project button and
now we can create Paths.
Let's Build this API
A path is a relative URL for our API calls, for this example, we will create two paths, /stocks and /portfolios. A path can have many actions associated as seen below:
| 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: Create Path: /portfolios
We next will create a PATH for the collection of portfolios, called /portfolios. We will enter the JSON of a portfolio, and save the schema of a portfolio to a Resource Type so we can reuse later and display in documentation. Note, you can also go to Resource Types and create a Resource Type of a portfolio, then create a path and assign that Resource Type.
Click on Add API Path and enter the data as shown in this image,
When you click on Add Path, you'll see the path appear in your list. Click on the settings icon on the right to edit the Actions you want to support for this path. Click the Generate Doc selection to generate OpenAPI. Click on JSON to see an example empty JSON object.
You'll also note under Resource Types, a Resource Type was created called Portfolio which is the schema created from your JSON. And, look under Data Types, you'll see a Data Type called Broker because automatically that Broker Data Type was created from the "broker" JSON object in the portfolio.
Resource Types are assigned to Paths, Data Types are object types in Resource Type properties, such as broker was a property of data type Broker in Portfolio.
Step 3. Add Path /portfolios/{id}/stocks
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.
After the stock is added, you'll see the new path now showing in the list. Again, you can view the Types on the left navigation.
On the left navigation, you'll see a Data section. For each path you created, you can add data for path and get an idea of the data response in JSON for each of your paths. You an add, edit and delete data.
Step 4. Add data to /portfolios
Step 5. Let's Deploy our API to the World
Now that you have create your paths, types and data, you can now deploy those Paths to the cloud creating an Endpoint and giving your external users access keys to connect to your Endpoint.
To create an Endpoint, see under Endpoints, click on Endpoints and then configure the panel on the right. Enter the names as shown below and click create.
You'll see all the information for the Endpoint with the URL at the top of page. You can instantly send requests to your new Endpoint, a curl command is provided, or use PostMan/Insomnia, etc. to send CRUD requests to your Endpoint.
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
Step 6. Share Your Endpoint on website
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 a completely new entity, including the data is separate as well. If you make changes, you can deploy a new Endpoint to keep previous verisons still available.
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.