User Documentation

Design API

Quick Start

Create a Collection

Add Items to Collection

Add Item to Collection using a REST

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

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

Creating Sub-Collections



Design API

Designing your API involves creating collections, resources and types. Collections are list of instances of your resources, types are objects used in resources.

For example, if you wanted to have a REST endpoint for a list of cars, you would create a collection of cars ...note the collection is plural. The resource would be car. To find a car in a collection would be /cars/id.

Quick start

The quickest way to get started is to log in from the home page and use the RestPoint UI. A sample project is created for you that you can browse. To create a project, click on the plus icon and enter the information 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 Project

Create a Collection

The quickest way to create a collection is to click on Collections menu in left navigation, then fill in the information on the right. Name will be the collection you will use in the url. Enter the JSON of the resource, for example, see the following image for creating a list of dealerships. This is a powerful feature of RestPoints to be able to enter JSON and have a collection auto-generated. After the collection is created, you can go to the resource and make any changes to the fields of a resource.

Create 'Dealerships' Collection

When you click on create, a dealerships collection will be created and appear in the menu under Collections on the left. On the right, you'll see the list of dealerships, which now has the first item in the list that you specified on the created.

You'll also note under resources, a dealership resource was created. And, look under types, you'll see a type called address, because automatically that address type was created for the object.

After 'Dealerships' Collection created

Add Items (data) 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 Item to Collection Using REST

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://www.restpoint.io/_ah/api/restpoints/v1/projects//collections/
  
	

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

	 curl -X POST -H "x-api-key:" 
    https://www.restpoint.io/_ah/api/restpoints/v1/projects/project-name/collections/collection-name
    -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. When the resource is created, automatically the associated collection is created.

So lets create an example Customer resource as follows:

Create Customer resource

After creating the resource, you'll see all the types in a list when you click on the resource in the menu on the left. Now, you'll also see a collection called mycars under the Collections list and you'll see the all the properties and first default item created. You can click to edit this item.

The following shows an example of each type possible for creating a resource.

	
  		{ 
  		     "name" : "name", 
  		     "description" : "description for name",
  		     "type" : "string | integer | number | boolean | resource | type | collection"
  		}
	
  

The following shows an example of an array, type will be array and items will be the type of the item.

	
  		{ 
  		     "name" : "name", 
  		     "description" : "description for name",
  		     "type" : "array",
  		     "items" : "string | integer | number | boolean | resource | type | resource",
  		}
	
  

Change Type of a Field in a Resource

At any time you can change any fields type by clicking on the Type or Resource and see the list of fields to the right. 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.

So lets change a field as follows:

Change Resource field 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, Customer is a resource and address is a type. If we want to have a collection of Addresses, then we would make a Resource called Address.


Deploy API's to Endpoints

Deploy Collection 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, your new endpoint does not have any data in it, it is a completely separate deployment.

Four endpoint access keys are provided for users to connect to your endpoint - full access, read access, create 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

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

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

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 values later.

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

Creating Sub-Collections

Now, lets say we have a collection called Dealership and we'd like each Dealership to have a collection of cars. We can add a car to the dealerships/id/cars, as below ...

Add a car to a dealership's cars collection

Then after adding that car, you'll see a dropdown menu on the top of the screen for a collection, this menu contains a list of the sub collections

How to view dealerships sub collections