User Documentation
1. Overview
2. Create a Project
3. Design Resources & Data Types
4. API Paths
5. Error Responses
6. Path Params
7. GraphQL
8. Data
9. Business Logic
10. Response Overrides
11. Webhooks
12. Docs
13. Prototypes: Deploy Endpoints
14. Share Endpoints
1. Overview
Restpoint.io is a SaaS service enabling anyone to design an API then auto-generate a real API backend with an embedded database. The goal is provide a working API backend that responds like the final API before any back end coding starts. This allows users to try and test drive the API user experience and give feedback. This will flesh out issues and problems that can be fixed early and cheaply and virtually guarantees sucdessful APIs.
You start designing APIs by creating a project. Then you will proceed to define the API paths and resources. At any time, you can click to deploy the API backend which will create a standalone API backend that you can send API requests to by any tool such as Curl, Postman or Insomnia. As you iterate, all the previous backends you created can co-exist so users are not left with broken links.
On the left navigation, you'll see three sections or phases. The design phase is no code using the UI to add paths, resources, error handling, etc. using our graphical UI. The Advanced phases enables higher fidelity to your API backend that may entail low code, such as adding data, business logic, custom responses, custom documents and much more. The Deploy phase enables auto-generating real API backends with embedded databases ready for API requests.
So lets get started creating a project and designing APIs !
2. Create A Project
Users get started by creating a project. A project can be a small API such as a microservice or a larger enterprise API, whichever works for the use case.
When creating a project, you can choose to import an OpenAPI doc, Postman collection or Jumpstart script or just create an empty project. For your first project, enter a name and description, select no import and create an empty project.
After the project was created, you will see the options on the left navigation to start creating resources and adding paths.
3. Design Resources and Data Types
We can go straight to API Paths and start adding paths, but the easiest way to get started is to create a Resource first that will be assigned when we create a path. For example, a Resource called Customer may have properties such as name, address, city and state. When creating a Path, you will have the option to select the resource. For example, if we created a path called /Customers, we would select the resource Customer. It is a recommended pattern to name resources and paths like this, such as a /pets path would be assigned a resource named Pet.
Often your resource has a property that is a collection of properties, such as a Customer resource may have a property called Address, which may have street, city and zipcode properties. These objects are referred to as Data Types. These objects differ from Resources as Data Types cannot be assigned to paths. Data Types are reusable objects used to describe properties in Resources or other Data Types as well.
Resource and Data Types can be created using the Form builder or a JSON example can be pasted in the the provided text area. At any time a Resource or Data Type can be edited.
Note: when specifying JSON to create Resources and Data Types, a Resource or Data type name can be specified within the JSON name property. For the example, if you specify the following JSON, a different Data Type will be created for each shippingAddr and billingAddr.
{
"shippingAddr": {
"name": "Jane Doe",
"description" : "10 Main Street"
},
"billingAddr": {
"name": "Jane Doe",
"description" : "10 Main Street"
},
...
Instead, specify the Data Type name or Resource name using a colon after the property name, now both shippingAddr and billingAddr will be of the Data Type Address:
{
"shippingAddr:Address": {
"name": "Jane Doe",
"description" : "10 Main Street"
},
"billingAddr":Address": {
"name": "Jane Doe",
"description" : "10 Main Street"
},
...
4. API Paths
Now that we have created a Resource, lets create an API Path. Create paths by clicking on the API Paths on the left navigation then see the Add API Path button. We will show how to create a path using an example. A window will pop up with the following fields:
Path: API Paths use the OpenAPI convention for naming paths, for example, /portfolios or /portfolois/{id}/stocks. Note, when creating paths with id's, use the OpenAPI convention of brackets, for example {id} or {portfolioId}.
Return Single Resource or Collection: specify if the path will return a single resource or a collection of resources. For example, /portfolios would be a collection of Portfolio resources and /top-porfolio would be a single portfolio resource.
Choose a Resource Type: choose the Resource Type that will be managed by the path, for example, if your path is /portfolios/{portfolio}/stocks, then the Resource Type is the last one, Stock.
If you choose "Enter Example JSON Resource", enter a name then paste or type in the JSON object for an example Resource in the text area. A Resource will be created by that name and the JSON will be used to create a Resource matching the properties in the JSON object. This is handy when you have the JSON and want to quickly create the path "on the fly".
5. Error Responses
Default error responses are provided so you do not have to create any error responses right away. As you design your API and it comes time to customize your error responses, you'll click on Error Responses on the left navigation, create an Error Resp, then configure all the http codes you wish to customize the error message.
After you have configured error messages, you can assign to a path. Go to your API paths page, select the gear icon on right for the path you wish to assign the error messages to and select the error messages.
These error responses will override system provided error messages when you make requests on your deployed API backend prototype.
Error Responses can also be added to Action configuration. For example, click on GET or POST for a path and assign a Error Response. This enables generic error messages to be applied to specific actions while error messages applying to all actions can applied to the Path configuration.
6. Query Parameters
Query parameters are configured in a similar manner as error responses. Configure the path parameters by clicking on Path Params on the left navigation, then add the path parameters.
Now to assign the query parameters, go the API Paths page and select an Action for the path, such as GET. A window will pop up for you to assign the query parameters to this path action.
7. GraphQL
Use the helpful GraphQL statement helper that generates the GraphQL queries and mutations supported for the paths you have configured. Note, the dash or hyphen is not supported in GraphQL but we support this to help with quick prototyping.
For queries, using our portfolios path example, would be queried as follows:
query { portfolios { id, name, description} }
Nested paths, such as /portfolios/{portfolioId}/stocks, can be queried using GraphQL as follows:
query { portfolios { id, name, description, stocks { id, name, ticker} } }
For mutations, the path portfolios supports the following:
Create Portfolio
mutation { create_portfolios(input: {id:"1", name:"Tech Stocks"}) {id,name}}
Update Portfolio
mutation { update_portfolios(input: { id: "1", name : "Bank Stocks" }) { id, name }}
Delete Portfolio
mutation { delete_portfolios(input: { id: "1" }) { id }}
8. Add Data
When you create a project, an embedded database is created for the project. And for each API path created, a data table is created seamlessly for the path. For example, when an API path, /portfolios/{id}stocks was created, a data collection called /portfolios/{id}/stocks will be created and data objects can be added, edited or removed for that collection in the Data Collections section.
9. Add Business Logic
Prototypes can get very realistic when business logic is applied. When API requests are sent, pre and post request scripts can be configured to execute. This logic can be used for such actions as validation of input, checking if specific data is already in a collection, etc. The scripting is based on Apache Velocity, more info on the scripting can be found at https://velocity.apache.org/engine/2.3/user-guide.html#references
For example, when a POST request is sent, the Pre Request Script is executed before the object is added to the collection. After the object is added to the collection, the Post Request script is executed. See the Examples select list provided to help you design script, click on an item in the select list, you can browser then copy/paste or click to insert script into the text area.
The following is an example pre request script when adding a stock to a portfolio:
## add to list of stocks if not there
#if ( $OBJECT.id == "" )
$ERROR = "Please provide the id of the stock to add"
#end
## a stock must exist in the /stocks collection to be added to a portfolio
#set ( $stocks = $PATHS.get_path("stocks").get_collection() )
#if ( !$stocks.has_object($OBJECT.id) )
$ERROR = "Could not find stock with id: $OBJECT.id"
#end
The following is an example post request script to send a Slack alert when a portfolio was created:
## send a message to Slack when a portfolio is created
#set ( $resp = $WEBHOOKS.get_webhook("slack").post() )
#if ( ! $resp.success() )
$ERROR = $resp.get_error()
#end
The following is an example post pre request script that returns a no longer supported api request message. "simple" is the Error Resp name, "410" is the error code defined in the Error Resp.
$ERROR = $ERROR_RESPS.get_http_code("simple","410")
A script has the following system objects available:
| Name | Description | Functions |
|---|---|---|
| $PATHS | All Paths | get_paths(), get_path("name") |
| $PATH | Target path | get_name(), get_collections(), get_collection("name") |
| $COLLECTION | Target collection | get_name(), get_object(id), get_object(object), get_objects(), create_object(id), add_object(object), update_object(object), delete_object(object), has_object(id), has_object_with("property_name", value), get_object_with("property_name"", value) |
| $OBJECT | Target object Note: $OBJECT.name is same as $OBJECT.get("name") | has_value("name"), get("name"), put("name", "value"), has("name"), toJSON() |
| $ACTION | Action | No functions, is a string i.e. "GET", "CREATE", "PUT", "DELETE") |
| $WEBHOOK | Webhook | post(), post($JSON) |
| $WEBHOOKS | All Webhooks | get_webhook("name") |
| $ERROR_RESPS | All Error Resps | get_http_code("error resp name", "error code"), has_http_code("error resp name", "error code") |
| $JSON | JSON (used for webhooks) | get("name"), put("name", value), create(), create("{ }") |
| $HTTP_REQUEST | HTTP Request | get_parameter("name"), has_parameter("name"), get_header("name"), has_header("name"), get_attribute("name"), set_attribute("name"), has_attribute("name") |
| $LOGGER | Logs are shown when errors occur | log("message") |
| $ERROR | Return error if $ERROR assigned a value | $ERROR = "Could not find object" |
For custom error codes, use scripting to return customer error codes in conditional logic. For example, if GET /customers is no longer supported, enter the following in the Pre Request script for GET:
$ERROR = $ERROR_RESPS.get_http_code("simple","410")
Note the first parameter ("simple") is the Error Resp name, the secondar parameter ("410") is the http code created in the "simple" Error Resp;
10. Response Overrides
When you deploy your API backend prototype, API request responses have a default common format that you will see. Sometimes, if you need to change this format, you can override the response for each path and each action for the path. To override the response, see Response Overrides on the left navigation and choose the path, then click Create.
Once you save your Response Override, you can click to test and enter manually an example object that will be used to show you the Response Override.
11. Webhooks
Webhooks are used to POST information to external webhooks. For example, to configure a Slack webhook, enter the name and description, then external webhook URL and headers. Headers are colon separated and comma delimted, for example, to add two header values: query:yes, add:no. See the following:
After the webhook is configured, webhooks can be execute in scripts. To execute the Slack webhook that we just configured in a script would be would as follows:
$WEBHOOKS.get_webhook("slack").post()
For more advanced webhooks, you also have the option to create the JSON. $JSON is a handy utility to create JSON for webhooks. To add a nested JSON object would be: $data = $JSON.create().put("firstname", "JohnDoe").put("lastname", "Doe") $JSON.put("text", "test").put("data", $data) $ $WEBHOOKS.get_webhook("test").post($JSON)
12. Docs
Many documents are provided by default or you can create your own documents. The easiest way to create your own documents is to create a doc and import the system doc as a starting point and then make the changes you need. For example, if you wanted to create your own modified OpenAPI document, you would click to create a new document, then import the system doc called OpenAPIv3.
Documents provided by default are:
OpenAPI: Auto generates OpenAPI v3
SwaggerUI: Generates the web page to view your API in SwaggerUI
Redocly: Generates the web page to view your API in SwaggerUI
Postman Collection: Auto generates a Postman collection to send requests to your prototype
GraphQL: Generates a spreadsheet of API requests
Guidelines Check: Generates a PDF of the issues that break the default API Guidelines
Design Review: Generates a PDF of the default Design Review doc
13. Prototypes: Deploying APIs
Once you have designed resources, paths and added data, you can now deploy those Paths as Endpoints for external users to send API requests. Prototypes can look and feel just like the end API since underneath these are real deployed APIs in the cloud.
To deploy the prototype, configure the name, base path and select the paths. The base path is used for the deployed URL, typically, /api. Deployed prototypes are self contained deployments so multiple versions can deployed simultaneously as you iterate towards completion.
Four access keys are provided for users to connect to your Endpoint using the x-endpoint-key header - full access, read access, create/read only and me only access. Using the full access key provides full read and write access to all items, using the read access keys provides read access to all data, the create/read key provides create and read access, the me only access means you can read/write your data. Note, when using the me only access key, you must provide your personal api key, i.e. x-api-key in the header along with x-endpoint-key.
14. Share Your Deployed APIs
Click share on the Endpoint so anyone can find your shared endpoints by searching on your user name on Shared User Endpoints