Getting Started with the API Console
Tags: api, rest, beginners, tutorial
Published: 2019-10-29 12:58:27

Have you ever wondered how to debug or play with your cloud code in a comfortable and fast way … without any coding? Because I think it can be a huge pain. 

Most probably you already know that Parse Server works very well with the REST API. If you feel the need to interact with the REST easily, you have come to the right place. Let me introduce you to the SashiDo’s API Console, part of our Dashboard. In brief think of the API Console as a simpler version of [Postman](https://www.getpostman.com/) and so easy to use that you will feel like a magician.

Now I will shed some light on how to use our API Console and shed some more light on:


1. [What is an API](#whatisanapi)
2. [What is a REST API](#whatisarestapi) 
3. [How to use the API Console in SashiDo’s Dashboard](#theapiconsoleinsashidosdashboard)
4. [Request types](#requesttypes)
     * [GET requests](#getrequests)
     * [POST requests](#postrequests)
     * [PUT requests](#putrequests)
     * [DELETE requests](#deleterequests)
5. [How to test ACLs and run requests as a specific user](#testyouraclsandclpsbyrunningrequestsasaspecificuserofyourapp)
6. [How to call your Cloud Code functions](#callyourcloudcodefunctions)
7. [How to export the API Console calls to cURL and test them in the Terminal](#exportcallstocurl)
8. [Useful links](#usefullinks)
9. [Fin](#fin)



## What is an API 

The ability to link with other programs and devices is an amazing thing. We are all connected to the world and each other like never before. But how does data come from one point to another - from here to there. How do different applications and devices connect with each other to allow us to do different jobs with just a few clicks?
The little-known warrior of our connected world is the Аpplication Programming Interface or [API](https://medium.freecodecamp.org/what-is-an-api-in-english-please-b880a3214a82). 
It is the engine behind the scenes that we take for granted but it is what makes possible all the interactivity we have come to expect and rely upon. In our context, the API is a set of functions that allow the creation of applications that access the features or data of other applications or services.

![api--1-](https://media-blog.sashido.io/content/images/2018/07/api--1-.png)


## What is a REST API

One of the most popular types of APIs is REST or, as they’re sometimes known, RESTful APIs. REST or RESTful APIs were designed to take advantage of existing protocols. While REST - or Representational State Transfer - can be used over nearly any protocol, when used for web APIs it typically takes advantage of the HTTP protocol.


Parse Server uses the REST API so basically you can interact with the Parse Server from anything that can send an HTTP request. There are many things you can do with the Parse REST API. For example:

* A mobile website can access Parse Server data from JavaScript.
* A web server can show data from Parse Server on a website.
* You can upload large amounts of data that will later be consumed in a mobile app.
* You can download recent data to run your own custom analytics.

In-depth knowledge of how to work with the Parse REST API is available on the official [Parse Server REST API Guide](https://docs.parseplatform.org/rest/guide/).

Now, after you have an understanding of how the Parse Server communicates with the outside world you might want to try some actual requests, be it to get a hands-on experience, do a quick proof of concept, or just quickly test something out. You have a few options on how to do it - write client-side code, use a REST client, or simple cURL commands. But that can be a laborious process which takes away valuable time that you could be putting toward designing great experiences for your users. That’s why we made this part of your job easier by providing the **API Console**.



## The API Console in SashiDo’s Dashboard

The API Console provides a graphical UI for exploring your Parse Server API's resources and interacting with it. It has a beautiful interface and is pretty easy to use. You can compose requests, inspect server response, generate client cloud code calls and export cURLs painlessly

![APIConsole](https://media-blog.sashido.io/content/images/2018/07/APIConsole.jpg)

You will find SashiDo’s API Console when you enter the **Dashboard**, choose the **app** you want to work on, navigate to **Core** and then you will see the **API Console**.


Here are a few things you can do with the API Console:
* Create, read, update, and delete objects
* Run requests as a specific user of your app (to test your ACLs and CLPs)
* Call your Cloud Code functions and start background jobs
* Export the calls to cURL to test them in your Terminal or Shell

So, let's go directly to our API Console and have a look there. You can try out some queries and take a look at what the server returns. 

When you open the API Console you will find a toggle on the upper right corner, - that is where you can choose whether or not to use the **Master Key** when you perform sensitive API calls. Talking about sensitive API calls you will find some additional info about the use of **Master Key** in the [Parse official REST API guide](https://docs.parseplatform.org/rest/guide/#security) in the Security section.
![Masterkey](https://media-blog.sashido.io/content/images/2018/07/Masterkey.jpg)

Using the Master Key will give you access to data ignoring all the ACLs and CLPs. If this isn't a requirement for your use case, you can switch off the Use Master Key toggle

## Request types


![ezgif.com-gif-maker--4-](https://media-blog.sashido.io/content/images/2018/07/ezgif.com-gif-maker--4-.gif)

Have you ever asked yourself what is the difference between **GET** and **POST** requests, or when to use the **PUT** request? Having basic information of how to execute HTTP methods with an API Console is a useful knowledge while exploring and trying out APIs. Let’s look through the different request types.

### `GET` requests

**GET** requests are the most widely used methods in APIs. You can use the **GET** method to **retrieve data from a server at the specified resource**. For example, say you have an API with a **classes/Users** endpoint. Making a **GET** request to that endpoint should return a list of all available users.

![get-2507-edited](https://media-blog.sashido.io/content/images/2018/07/get-2507-edited.gif)

Having in mind that a **GET** request is simplest, inquiring for statistics and no longer modifying any assets, it is considered a [safe and idempotent method](http://restcookbook.com/HTTP%20Methods/idempotency/).
 
Whilst you're developing tests for an API, the **GET** method will likely be the most common type of request made, so it's essential to test every acknowledged endpoint with a **GET** request.


## `POST` requests

**POST** requests are used to send data to the server’s API to create а resource. The data sent to the server is stored inside the request body of the HTTP request.
The simplest example is a “hello message” on a website. When you fill out the inputs in a form and hit **Send**, that data is put in the **response body** of the request and sent to the server. 

![Post-25072018-edited-1](https://media-blog.sashido.io/content/images/2018/07/Post-25072018-edited-1.gif)
 
It's worth noting that a **POST** request is **non-idempotent**. It mutates data on the backend server (by creating or updating a resource), as opposed to a **GET** request which does not change any data. Here is a great explanation of [idempotency](https://www.infoq.com/news/2013/04/idempotent).
 
Here are some tips for testing **POST** requests:
* Create a resource with a **POST** request and ensure a 200 status code is returned.
* Next, make a **GET** request for that resource, and ensure the data was saved correctly.
* Add tests that ensure **POST** requests fail with incorrect or ill-formatted data.
 
 
 
## `PUT` requests

Just like **POST**, the **PUT** requests are used to send data to the API to update a resource. The difference is that PUT requests are idempotent. That is, calling the same **PUT** request multiple times will usually produce the identical result. In comparison, calling a **POST** request many times can have side effects of creating the same resource more than one time.

![put-25072018-edited](https://media-blog.sashido.io/content/images/2018/07/put-25072018-edited.gif)

Testing an APIs **PUT** request is very much like testing **POST** requests. But now that we recognize the difference between the two, we are able to create API tests to affirm this behavior.

Check for the following things when you test the **PUT** requests:
* Repeatedly calling the **PUT** request always returns the same result.
* After updating a useful resource with a **PUT** request, a **GET** request for that useful resource should retrieve the new data.
* **PUT** requests will fail if invalid data is sent in the request body, hence the specified resource will not be updated.




## `DELETE` requests

The **DELETE** method is precisely as it sounds: delete the resource of the desired URL. This method is one of the most frequent in RESTful APIs so it is top priority to recognize the way it works.

If a brand new user is created with a **POST** request at the **classes/User** endpoint, and it can be retrieved with a **GET** request to **classes/Users/UserID**, then creating a **DELETE** request to **classes/Users/UserID** will completely remove that user.

**DELETE** requests must be heavily tested on the grounds that they normally dispose of information from a database. Be careful when testing **DELETE** methods. Ensure you are using the precise credentials and no longer checking out with actual user records.

In a normal test case, a **DELETE** request should look like this:

![delete-26072018-edited](https://media-blog.sashido.io/content/images/2018/07/delete-26072018-edited.gif)

* Create a brand new user with a **POSТ** request to **classes/_Users**
* After the **POST** request was successful, make a **DELETE** request to the endpoint **classes/Users/UserID**
* Next, a **GET** request to **classes/Users/UserID** will return a **101 status code**, with an error **Object not found**, in the Results, if the **DELETE** request was successful.



##Test your ACLs and CLPs by running requests as a specific user of your app

![Run-as-...user-edited](https://media-blog.sashido.io/content/images/2018/07/Run-as-...user-edited.gif)

You can call a function as a specific user and check if the user has access to the resources you are calling. This is a very easy and simple way to verify if you have correctly implemented the ACLs and CLPs for a certain user of yours. Just enter the username or user ID in the **Run as..** field and perform the command you want to receive results for.



## Call your Cloud Code functions 

Calling your [Cloud Code](https://docs.parseplatform.org/cloudcode/guide/) functions has never been so effortless as it is with our API Console. By default there is a simple cloud code function sample in the **functions.js** file in your Cloud Code and in your [Github Repo](https://github.com/parsegroundapps/pg-app-tynwrjdecdmr69ke5d8fec6ixljzx5/blob/master/cloud/functions.js#L5) in the cloud folder so we can use it and show you how you can call a function through the API Console. 

![apiConsole](https://media-blog.sashido.io/content/images/2019/03/apiConsole.gif)

You will simply need to go to the API Console, choose the type of request, which will be **POST**, and choose the endpoint. Select the **POST** request and the endpoint **functions/hello**, click on the **Send query** button and see if the Dashboard shows you “*Hello from SashiDo’s simple cloud code*” message.



## Export calls to `cURL`

[cURL](https://www.rosehosting.com/blog/curl-command-examples/) is the most used command line tool for making API calls. It is great for complex operations since it is scriptable and versatile. It combines the command, the credentials, **like application ID**, **REST API key**, your desired **API endpoint**, **query parameters** and more in a single command. 

![exporting-cURL-26072018-edited](https://media-blog.sashido.io/content/images/2018/07/exporting-cURL-26072018-edited.gif)

There is a very easy way to create cURL commands. You can construct a request in our API Console and convert it to cURL using the **Export to cURL** button. It is that easy. I am sure this will save a lot of your time if you have to write it on your own. For example, if you experience an error with your Cloud Code and you are contacting our Help Desk it is a good idea to run the same request or query through the API Console, export it to cURL and then include it in the steps to reproduce. Our Dev and Engineering team will be happy to resolve your issue in a faster and more adequate manner.




## Useful links:

[What is an API? In English, please.](https://medium.freecodecamp.org/what-is-an-api-in-english-please-b880a3214a82)
[RESTful API definition](https://searchmicroservices.techtarget.com/definition/RESTful-API)
[Command line tool and library for transferring data with URLs](https://curl.haxx.se/)
[How to protect Rest API key for Parse in html application](https://stackoverflow.com/questions/18072123/how-to-protect-rest-api-key-for-parse-in-html-application)
[7 HTTP methods every web developer should know and how to test them](https://assertible.com/blog/7-http-methods-every-web-developer-should-know-and-how-to-test-them)

For easing you even more we have also made a video about the API Console. 
<iframe width="854" height="480" src="https://www.youtube.com/embed/Aq4CAegumNs" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>


## Fin

There you go! Now you have some ideas on how you can play around with the API Console or debug issues without writing a single line of code. Now it is your turn to explore it and enjoy the easiness of coding!