API Basics

Learn more about REST APIs and how to interact with them.

What is an API?

API stands for Application Programming Interface. APIs enable communication between two software components, typically a client and a server. The application sending the request is the client, and the application sending the response is the server. When interacting with the Mobile Text Alerts API, the Mobile Text Alerts database is the server, and you send requests as the client.

There are different types of APIs, the MTA API is a REST API.

REST APIs

REST stands for Representational State Transfer, a REST API is a way for software systems to communicate using HTTP. The main principle of REST APIs is statelessness, which means each request from a client to a server must contain all the information needed (no session stored on the server). The server processes the request and returns the necessary data as plain text.

HTTP Methods in REST

HTTP methods indicate the action the client would like to perform on a given resource. Examples of possible actions when calling the Mobile Text Alerts API: send a message, add/delete a subscriber, create a drip campaign, and many more.

Each HTTP method is mapped to a specific operation and is included with every request to the API.

HTTP Methods:

• GET - Retrieves data from the server.

  • Example: A GET request to the /subscribers endpoint would return a list of all subscribers.

• POST - Sends data to the server to create something new.

  • Example: A POST request to the /send endpoint would create a new message(s).

• PATCH - Updates existing data on the server.

  • Example: A PATCH request to the /threads/{threadId}/read endpoint would update the thread specified with {threadId}as Read.

• DELETE - Removes existing data on the server.

  • Example: A DELETE request to the /groups/{groupId} endpoint would remove the group specified with {groupId}.

REST API Responses

After making a request to the API, it will return a response that contains the following information:

• HTTP status code- This three-digit code indicates the outcome of the request

  • Example: 200

• Response Headers- This provides metadata about the response.

  • Example: Content-Type, Date

• Response Body/Payload- This is the actual data content of the response.

  • Example:

  {
    "data": {
      "messageId": "uuid",
      "totalSent": 1,
      "totalFailedInternationalRecipients": 0
    },
    "message": "Message Sent to 1 Recipient."
  }