This isn’t rocket science

Ready to unlock the power of the Unity API? Let’s get you started. Don’t worry if this is the first API you’re working with, you’ll soon notice this isn’t rocket science. We’ll cover everything from what tools to use to your very first “Hello World” API interaction. Put your propeller-hat on, this is where the fun starts.

API interaction

Any tool for making HTTP requests is suitable to work with the Unity API. Unity API is a RESTful API and follows most of the common agreements on HTTP Methods usage. Communication is done in JSON format so any request to the API should be a valid JSON document.

Requests

All request to the API should be sent via HTTP protocol using the right HTTP method for the call (see the table below for when to use which method). Requests that contain a request body should have a [html]Content-Type[/html] HTTP header with a description of content being sent (typically [html]application/json[/html]). Also, every request should be signed with a personal access token placed in the header. Sign-up to get your access token (it’s free).

Request example

[json]Authorization: Bearer MWQzMjQ2NjU1NjgxMGQwMzI3MzY0OTE5NmU0ZTQ2NzE3YzYxNmVkZGYxNGE1MWVjOGVkMjZlNjVjMzQ1NDY1NQ
[/json]

HTTP methods

HTTP statuses

Each API response contains a corresponding HTTP Status Code. Codes in the 200 to 299 range indicate a successful action and means that no error was encountered. Codes in the 400 to 499 range indicate that there was an issue with the request that was sent. You should check your code before trying again. Codes in the 500 to 599 range indicate a server side problem. It means that the Unity platform is having an issue and cannot fulfill your request at this time. Try again later.

HTTP responses

Typically every response contains a response body as a JSON document. An exception to this are DELETE requests. They always return an HTTP status of [html]204 No Content[/html] along with an empty response body. Most of the responses contain a requested object or a list of objects. In some cases results are wrapped in a structure that includes pagination info.

Response example with pagination

[json]{
	"controllerList": [
		{
			"id": "example string value",
			"serialNumber": "example string value",
			"activated": true,
			"projectId": "example string value"
		}
	],
	"page": 843,
	"size": 213,
	"total": 525
}
[/json]

HTTP clients

As said before, you can use any HTTP client to interface with the Unity API. To get your started, below is an overview of the most commonly used ones.

cURL

cURL is installed by default in most popular *nix distributions. It is a widely spread tool and a library for making HTTP requests. cURL is a command line utility and does not have any GUI.

Simple request example

[json]curl 'https://developer-api.etwater.com/api/v1/hello-unity'
[/json]

Response

[json]{
	"greetings": "Hello from Unity platform",
	"requestMethod": "GET"
}
[/json]

The request method should be set using the [html]-X[/html] console parameter:

PUT request example

[json]curl -X PUT 'https://developer-api.etwater.com/api/v1/hello-unity'
[/json]

Response

[json]{
	"greetings": "Hello from Unity platform",
	"requestMethod": "PUT"
}
[/json]

Request headers should be set using the [html]-H[/html] console parameter:

Content-Type and Authorization headers example

[json]curl -X PUT -H'Content-Type: application/json' -H'Authorization:  Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/hello-unity/auth'
[/json]

Note that in the above request [html]$ACCESS_TOKEN[/html] is a placeholder and should be replaced with your real access token you received when signing-up for API access.

Response

[json]{
	"greetings": "Hello from Unity platform",
	"requestMethod": "PUT",
	"isAuthenticated": true
}
[/json]

POSTMAN

On of the most popular GUI applications to interact with HTTP web services is POSTMAN. It has an intuitive UI and is available on all major platforms as a native application or as a Google Chrome extension.

POSTMAN request and response examples

In POSTMAN that last cURL request will look like this:

And as an added benefit you can generate cURL requests from within the POSTMAN UI:

PHPStorm IDE REST Client

PHP, as the most commonly used language in web development, is often used with a PHPStorm IDE. This IDE has a built-in REST Client UI tool that could be used to interact with the Unity API.

You can find the REST client under the Tools menu section:

And that last cURL example in this client will look like:

In general, everything remains the same, except you have an easier way to set HTTP request options with the IDE UI.

Next steps

Now that you know how to interact with the Unity API and have several tools at your disposal to get started, it’s time to get to know the main API endpoints, and after that make sure you check out the full API specification.