User Documentation

Overview

Quick Start

Create a Collection

Add Items to Collection

Add Object to Collection using a REST

Add SubCollection to Collection

Create a Resource

Change the type of a field in a Resource

Using Types vs Resources

Deploy API's to Endpoints

Deploy Collection using an Endpoint

Share an Endpoint

Test Driving API's

Walk through example using PostMan Rest client

Using RestPoints API's

View API's using Swagger

Browse API in Swagger

Advanced

Examples of Creating Collections using JSON



Overview

Designing your API involves creating collections, resources and types in your Sandbox, then deploying collections in endpoints to production for external users to access.

Restpoint uses the collection metaphor, which means collections are denoted as:

/collectionName/:id/subCollectionName/:id

for example: /portfolios/1234/stocks would return a list of stocks in portolio 1234
/portfolios/1234/stocks/35 would return stock 35 in portfolios 1234

RestPoint provides a graphical administrator and API. For Sandbox API requests, set your x-api-key in the header to the value found by clicking on the ME button top right of the screen. For Production API requests to endpoints, set the x-endpoint-key in the header to one of the endpoint keys provided when you created the endpoint.

Quick start

Let's build an API called stockquiz 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

The quickest way to create a collection is to click on Collections menu in left navigation, add the collection name and description. We will specify the resource to be Portfolio, which does not exist in our current project, so let's provide the JSON object of a portfolio and let RestPoint auto-generate a Portfolio resource and add 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 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 create, 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 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.

Add Stocks Collection to Portfolios

Add Portfolio Using API

When you have created a collection in the UI, you can use any REST client to access the collection by specifying the x-api-key in the header and calling GET. To use curl,

	 
  curl -H "x-api-key:" https://api.restpoint.io/_ah/api/restpoints/v1/projects/stockwhiz/collections/portfolios
  
	

You can also use the REST API to add an item to your collection.

	 curl -X POST -H "x-api-key:" 
    https://api.restpoint.io/_ah/api/restpoints/v1/projects/stockwhiz/collections/portfolios 
    -H "Content-Type:applications/json" --data "\"name\":\"John Doe\"}"
    
  

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.

Deploy API's to Endpoints

Deploy Collection to Production using an Endpoint

Now that you have a collection, with data, you don't want to give anyone your api key since they would get full access to all your projects. Instead, you can create and deploy an endpoint then give your external users an access key to connect to your endpoint. 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, click on Endpoints and then configure the panel on the right. Specify the collection names and click create. Then choose an endpoint key to give your users so they can access the endpoint collection.

Create Endpoint

After the endpoint is created, you see the following:

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:

Endpoint created

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 an 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.


Test Driving API's

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


Using RestPoint API's

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

View Endpoint API's

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

View Endpoint 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" : [] 
  		}