Getting Started with the API Console

by Severina Paneva

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 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
  2. What is a REST API
  3. How to use the API Console in SashiDo’s Dashboard
  4. Request types
  5. How to test ACLs and run requests as a specific user
  6. How to call your Cloud Code functions
  7. How to export the API Console calls to cURL and test them in the Terminal
  8. Useful links
  9. 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 does 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.

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 which access the features or data of other applications or services.

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.

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

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 in the Security section.

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

Have you ever asked yourself what is the difference between GET and POST requests, or when to use the PUT request? Having a 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.

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.

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.

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.

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.

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

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:

  • 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

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 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 in the cloud folder so we can use it and show you how you can call a function through the API Console.

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

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.

What is an API? In English, please.

RESTful API definition

Command line tool and library for transferring data with URLs

How to protect Rest API key for Parse in html application

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.

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!