User Documentation

Overview

Quick Start

Create a Collection

Add Items to Collection

Add Object to Collection using a REST

Add SubCollection to Collection

Deploy Collection to Endpoint

Deploy Collection using an Endpoint

Share an Endpoint

View Endpoint API

Create a Resource

Change the type of a field in a Resource

Using Types vs Resources

Using RestPoint API

Walk through example using PostMan Rest client

Browse API in Swagger

Advanced

Examples of Creating Collections using JSON



Overview

RestPoint enables you to build a "western movie set" of your API, looks and feels like the API, with a data backend, so you can play with it, plug into your beta applications or test scripts, and involve customers early to get thier feedback.

So lets build an API fast, as in minutes, because we do all the work, you just have to tell us the properties your need in your resource modeling. Which is even easier to do if you just specify what the JSON of a an object is that you want to have a collectio of.

What does that mean? For example, if you want to have a list of Suppliers, then we need the properties of what is a Supplier. So you can give us a JSON object of a Supplier, or you can manually create a resource called Supplier, with properties, then create a collection of suppliers. If a Supplier contained an object like address, which is a street/city/zipcode, then address would be considered a type.

RestPoint has a nice feature that auto creates a resource, collection and types from a JSON object. So you can specify the JSON of a supplier and we'll create the API and backend.

The best way to to get started with RestPoint is to work through an example in the next section, Quick Start, and email restpointinfo at gmail.com with any questions.

Quick Start

Let's build an API to manage stocks in a portfolio. The quickest way to get started is to log in and use the RestPoint UI. To create the project, click on the plus icon and enter the project name & description on form on the the right side. When a project is created, you can then create collections, resources and types. For now, do not enter anything in the OpenAPI yaml which is used for initializing a project from a OpenAPI yaml doc.

Create StockWhiz Project

Create a Collection

So we would like to have the following API:

POST /portfolios
GET /portfolios
PUT /portfolios/:id
DELETE /portfolios/:id
POST /portfolios/:id/stocks
GET /portfolios/:id/stocks
PUT /portfolios/:id/stocks/:id
DELETE /portfolios/:id/stocks/:id

Let's get building this API. We need a collection of portfolios, then in each portfolio, we need a collection of stocks. So let's build a collection fast by using a RestPoint feature that takes a JSON object of a Portfolio and builds the Resoure, Collection and any types if needed.

The quickest way to create a collection is to click on Collections menu in left navigation, add the collection name and description. We will click to automatically create a resource from the JSON object, then provide the name of the resource, then provide the JSON object of a portfolio and let RestPoint auto-generate a Portfolio resource and add the JSON object to the collection. This is a powerful feature to be able to enter the JSON of an object resource and have the collection and resource be auto-generated. After the collection is created, you can go to the resource and make any changes to the fields of a resource.

Create Portfolios Collection

When you click on Add Collection, a portfolios collection will be created and appear in the menu under Collections 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 created.

You'll also note under resources, a portfolios resource was created. And, look under types, you'll see a type called Contact, because automatically that Contact type was created from the JSON object of the portfolio.

After Portfolios Collection created

Add Another Portfolio to Collection

Now you have a Portfolios collection, you can add data in the UI or use the REST API to add data to your collection. To add data using the UI, click on Collections then choose the collection from the drop down menu. You can click Add 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 Collection

Add Stocks Collection to 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 add the collection the same way we did for portfolios with the addition of a portfolio id, and add a JSON object for a stock to auto-generate a resource and collection. Note the portfolio id we are using is from the already existing portfolios. You can specify an id when you create objects, if you don't, a UUID is auto generated for you.

Add Stocks Collection to Portfolios

Deploy API's to Endpoints

Deploy Collection to Production using an Endpoint

Now that you have the portfolios and stocks collections created in your Sandbox, with data, you can now deploy those collections to a Production as endpoints and give your external users access keys to connect to your endpoints. Note, you can copy all the data from your Sandbox collections to your new endpoint, your new endpoint is a completely separate deployment in production.

Four endpoint access keys are provided for users to connect to your endpoint - full access, read access, create/read only and personal only access. Full access gives user full read and write to all items, read access gives users read access only to all data, create only means they can only create data and me only access means you can read/write your data.

To create an endpoint, see under Production, click on Endpoints and then configure the panel on the right. Specify the collection names and click create. You'll see all the information for an endpoint with the URL at the top of page. Choose an endpoint key to give your users so they can access the endpoint collection.

Create Endpoint

Endpoint Created

Further down on the endpoint screen, you will see the endpoint keys

You can give an access token to your external users, there are four types:

After the endpoint is created, you can access your endpoints over the web using curl using an endpoint key, lets use the full access key and call our new endpoint:

curl -H x-endpoint-key:37b6886d47aa49be8bbaa8a04ccffe3e https://api.restpoint.io/stockpicker-beta1/portfolios

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 in collections that they created, requires the users to authenticate to Google

You can configure a URL for a notification to be sent when any changes occur to the collection. A post is sent to the URL with the following body:

	{"user":"email",
	 "endpoint":"name",
	 "collection":"name",
	 "action": ["create", "update", "delete"],
	 "value": {JSON Object}
	 }
  

Share Your Endpoint

Click share on the endpoint so anyone can find your shared endpoints by searching on your user name on https://restpoint.io/userendpoints.html

Note the endpoint is completely separate from the project, including the data is separate as well.


View Endpoint API's

You can view your endpoint API's using Swagger UI or ReDoc. To view an endpoint's API, click on Endpoint and choose an endpoint from the menu. See the Swagger or ReDoc URL in a panel to the right at the bottom of the form.

View Endpoint API


Create a Resource

You can create a resource and specify all the fields, and meta data for each field.

Create Customer resource

Each field is defined as:

 
    {
    "name": "name of field",
    "description": "description of the field",
    "type": "choose [string, integer, number, boolean, array] or specify Resource or Type name",
    "item": "choose [string, integer, number, boolean] Note: needed only if type is array"
    }
  

The following shows defining a field by specifying a type:

 
    {
    "name": "name of field",
    "description": "description of the field",
    "type": "Contact",
    "item": "choose [string, integer, number, boolean] Note: needed only if type is array"
    }
  

The following shows defining a field that's an array of string:

 
    {
    "name": "name of field",
    "description": "description of the field",
    "type": "array",
    "item": "string"
    }
  

Change a Field in a Resource

At any time you can add, remove or change any fields type by clicking on the Type or Resource and see the list of fields to the right. To change a field, see the type field and change to one of string, integer, number, boolean or array. If the type is array, be sure to add the type in the items field - which could be any type or resource name, or the list of types specified previously. Any collection containing this type will be automatically be updated to this new type.

Using Types vs Resources

Types are created and updated the same way as resources. Think of types being the same as resources except Resources are in collections. Types are objects in a Resource, such as in our example, Portfolio and Stock is a resource and Contact is a type.


Using RestPoint API's

RestPoint's user interface uses the API, so everything you see in the UI can be done via API. The following walks through building an API using RestPoint API.

Walk Through Example using PostMan Rest Client

Here's an example how how to build a RestPoint using the API & PostMan
Getting started: Build a RestPoint

Browse RestPoint.io API

You can do everything in the UI using the API. Click on "Me" after login to get your access token for API
Browse RestPoints API


Advanced

Examples of creating collections using JSON

This example will create a collection and automatically create an array of nicknames.

	
  		{ 
  		     "name" : "John Doe", 
  		     "nicknames" : [ "Jon", "Buzz" ]
		}
	
  

This example will create a collection with a property called favorite of type car and a property called mycars that is a list/array of cars. Note, I use [] and {} for now, I can add the JSON values now or later.

	
  		{ 
  		     "name" : "John Doe", 
  		     "favorite:car" : {},
  		     "my-cars:cars" : [] 
  		}