Sinch Community

Shahzad_Ismail

REST (Representational State Transfer) is a set of architectural guidelines for implementing an API. The principles of REST were formulated by computer scientist Roy Fielding in 2000 and have since become the dominant paradigm for implementing APIs. This is because the REST paradigm is flexible and adaptable to client requirements. Unlike alternatives it is language and framework agnostic. It works in the principle level rather than the protocol level. An API is described as “RESTful” if it implements the REST paradigm. Sinch has plenty of RESTful APIs which allow developers to leverage capabilities like SMS messaging and automated email marketing. They get their power by having REST features like the following.

Client-Server Architecture

Like most applications and sites on the web, RESTful APIs follow a client-server architecture. This consists of three components:

Client – the API customer. This could be a developer writing an app or testing with Postman
Server – backend which hosts the API platform
Resources – capabilities of the API that developers can use to enhance their applications. Resources can be modified by create, read, update and delete methods.

As an example, let’s look at the Sinch SMS API. Clients, which are typically Sinch customers, can access it by signing up to Sinch and receiving an API token for authentication. They can then send requests to the API through their code or using Postman.

The XMS server hosts four resources:

Batches are sets of SMS messages that can be sent to one or more numbers.
Inbounds are incoming messages.
Groups are sets of phone numbers that can send or receive messages.
Delivery reports tell customers whether their messages have been successfully sent to their destination. Sinch clients can access these resources through HTTP requests to add capabilities to their applications.

Hierarchical architecture

RESTful architecture typically contains 3 tiers.

REST layer – this is the tier that communicates with the client. It responds to HTTP requests, transferring data in the form of JSON.
Service layer – this contains the business logic implementing API resources.
Data layer – this persists data in a database such as MySQL.

For example, the SMS API implements this in the form of a Multi Service Layer (MSL) platform. The REST and service layers are implemented by Spring-based component called Gateway and Adapter. Gateway has the ability to queue SMS messages for processing. Adapter is specialized to process MMS messages. In the SMS API, MySQL is used to implement the data layer, allowing customer data to be persisted and retrieved for later use.

HTTP Methods

RESTful APIs are normally accessed through HTTP requests. There are 9 different types of HTTP request but the four most common are GET, POST, PUT and DELETE. For example, one of SMS API’s resources enables processing of batches of messages. This resource contains:

POST methods to send and update batch messages. These tell Sinch servers to create and send a new message batch or to modify the parameters of an existing message batch, depending on what the customer wants to do.
GET methods to retrieve a batch of messages and retrieve a list of batches. This allows clients to keep track of their message batches.
PUT method to replace a batch
DELETE method tells Sinch servers to cancel a batch of messages.

Unique Resource Endpoints

One of the core principles of RESTful architecture is that API resources and methods are attached to URIs called endpoints. Endpoints have the same structure as a website URL, but instead of loading an application onto your browser, they enable you to send HTTP requests to the API.

Each endpoint specifies a particular resource. For example in the SMS API the endpoint https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches specifies the resource for sending a batch of messages. The ability to access API resources the same way you would access any other resources makes RESTful APIs an extremely powerful development tool and the backbone of modern web development.

Sinch REST APIs

Sinch has REST APIs for: