API Calls

We allow you to build applications that can interact with external services using their APIs—for example, building a joke app that shows a random joke using a Joke API.

If you are brand new to APIs, you may want to check out this in-depth APIs for beginners tutorial video.

What is an API?

The acronym API stands for Application Programming Interface. It lets a product or service (in this case, it's the app you are building ) communicate with other products and services through a secured channel without sharing much information about their implementation.

The two most popular API specifications are SOAP and REST. Just to give you a brief idea:

• SOAP: Simple Object Access Protocol uses XML for its message format and receives requests through HTTP or SMTP.

• REST: The acronym for Representational State Transfer is an architectural style followed by various APIs. REST APIs are known for their fast performance & reliability.

Most of the Web APIs you will be dealing with are the REST APIs with JSON format; this is the most predominant specification now.

Methods of API Call

While defining a REST API Call, you will need to specify the type of HTTP request method.

You can select among the following method types while defining an API Call on Digia Studio(expand the section to learn more):

GET request (Read data)

The GET request is commonly used for retrieving/reading data from a server, it doesn't allow any modification of resources present on the server.

GET Response Codes

• If the resource is found on the server, then it returns the response code 200 (OK) along with the response body, which is usually in JSON format.

• If the requested resource is not found on the server, then the server returns the response code 404 (NOT FOUND) and an empty body.

• In case the GET request is not properly formatted, then the server returns the response code of 400 (BAD REQUEST).

POST request (Create data)

The POST request is used for sending data to the server in order to create or update a resource. JSON format is usually used for sending the data to the server.

POST Response Codes

• If the request creates any resource on the server, then it returns the response code 201 (Created) and may return a response body.

• If the request doesn't create a new resource but rather modifies an existing resource, then the response code returned is either 200 (OK) or 204 (No Content), indicating successful completion of the request.

• If the server refuses or fails to authorize the request, then it returns the response code 403 (Forbidden).

DELETE request (Delete data)

The DELETE request is used for deleting any data present on the server.

DELETE Response Codes

• A successful HTTP DELETE request returns the response code 200 (OK) if the response includes an entity describing the status.

• If the request has been queued, the response code should be 202 (Accepted).

• If the request is complete, but the response does not include an entity, the response code should be 204 (No Content).

• If the resource to be deleted is not found on the server, the response code 404 (Not Found) is returned.

PUT request (Replace data - updates the entire data)

The PUT request is used for updating an existing resource present on the server. If the resource that is to be updated is not present, then the API may create the resource on the server.

PUT Response Codes

• If a new resource is created by the HTTP PUT request, the server returns the response code of 201 (Created).

• If an existing resource is modified by the request, either the 200 (OK) or 204 (No Content) response code is returned on successful completion of the request.

• If the resource is not found on the server, the response code of 404 (Not Found) is returned.

PATCH request (Modify data - helps in partial update)

The PATCH request is used to make a partial update of a resource present on the server. It is used for making a more precise update than the PUT request that is used if you’re replacing the entire resource entity.

PATCH Response Codes

• If the resource is successfully modified on the server using the HTTP PATCH request, the response code 200 (OK) or 204 (No Content) is returned.

• If the resource is not found on the server, the response code 404 (Not Found) is returned.

See a list of all response codes (HTTP status codes) that external services might return.

Let's see what you need to know to add an API call on the page below:

Setting up API Calls