We will step by step build a REST endpoint / service with screen shots.
1. Get your API token
The easiest way to log into RestPoint is to click on the Log in link on the home page Login and use your Google credentials. When you login, click on the "Me" button on the right and you will see your API key. The HTTP header x-api-key to has to be used for all API calls.
https://api.restpoint.io/_ah/api/restpoints/v1/me
Add the HTTP header x-api-key with value. You can reset your token anytime by calling
POST https://api.restpoint.io/_ah/api/v1/restpoints/me/api-token
Show /me in Postman REST client
2. List your projects
Get a list of your projects. The first time you log in, we create a sample project for you. Call
https://restpoint.io/_ah/api/restpoints/v1/projects
and take a look at the response links. You'll see the links to fetch a project. Go ahead and call GET on the sample project
"http://api.restpoint.io/_ah/api/restpoints/v1/projects/sample"
Show list projects in Postman REST client
3. Create a project
Create a project when you want to start fresh with a new list of collections, resources, types, endpoints, etc. Call
POST https://api.restpoint.io/_ah/api/restpoints/v1/projects
with a body
{ "name" : "my-first-project", "description" : "Having fun with restpoints !" }
Now you can get the project by calling
https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project
Show get project in Postman REST client
4. Create a collection in your project
The easiest way to create a collection is to post a JSON object (item) to a collection by name. If the resource does not exist, a resource will be auto created from the JSON object and the collection will automatically be created. To create a new collection in this manner, the following creates a collection by POSTing a JSON object of a restaurant:
POST https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/restaurants
with a body
{ "name" : "Al's Diner", "address" : { "street" : "100 Main Street", "city" : "San Francisco", "state" : "CA" } }
Show this create collection in Postman REST client
Now you can get the items in the restaurants collection by calling
https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/collections/restaurants
Show the restaurants collection in Postman REST client
5. Show the world, deploy collection endpoint
A project can have many collections, when you want to publish a collection to the world for anyone to interact with, you can create an endpoint with specified collections. When you create an endpoint, you will see three api tokens provided for users to access the endpoint using x-endpoint-key.
POST https://api.restpoint.io/_ah/api/restpoints/v1/projects/sample/endpoints
with a body
[ "name" : "beta", "collections" : [{ "name" : "restaurants" }] ]
API tokens provided are :
full-access-token: for users to read and write to any item
read-only-access-token: for users to only read items
create-only-access-token is for users to only read/write items they created
Show create rest service / endpoint in Postman REST client
Let's step through some other features of RestPoint. BTW, see more examples at
https://api.restpoint.io/_ah/api/restpoints/v1/examples
View the resource schema or definition for collection
In a previous step, we created a restaurants collection by POSTing an item to a named collection which means a resoruce is auto created from the JSON object. Now you can view the definition or schema of the restaurants resource that was created by calling
GET https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/resources/restaurants
Show the restaurants schema in Postman REST client
To see the schema with types such as restaurants address expanded, call
https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/resources/restaurants?expand=true
View the types in a project
Types are JSON objects, such as address in the above example, that are used in resources. To view the types in a project, call
GET https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/types
Show the restaurants schema in Postman REST client
To see the schema of a type, as in the elements of a type, call
https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/types/address
Create a resource
The other way to create a resource collection is to create a resource by specifying the schema, a collection is automatically created when a resource is created. In this case, we will create the address type first, then create the restaurant resource. To create the address type call:
POST https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/types
with body
{ "name": "address", "description": "", "fields": [ { "name": "street", "type": "string", "defaultValue": "", "description": "" }, { "name": "state", "type": "string", "defaultValue": "", "description": "" }, { "name": "city", "type": "string", "defaultValue": "", "description": "" } ]Now create the restaurants resource, specifying the address you just created above
POST https://api.restpoint.io/_ah/api/restpoints/v1/projects/my-first-project/resources
with a body
"name": "restaurants", "description": "", "fields": [ { "name": "address", "type": "address", "description": "" }, { "name": "name", "type": "string", "defaultValue": "", "description": "" } ]
View REST service / endpoint in Swagger
At anytime, you can view your REST service / endpoint in Swagger. Note you can append the x-endpoint-key for users to view the Swagger content
https://api.restpoint.io/swagger/endpoint.html?endpoint=beta&x-endpoint-key=4ab38fde4d644f7a99640f88f54fe163