The REST API

In This Article


Cheat Sheet

URLhttp://live.everlytic.net/api/2.0
TransportHTTP Requests
PayloadURL encoded form data

Introduction

REST (or Representational state transfer) is an architectural style that simplifies the design of Web Services. It's based on the concept that everything is a resource, and that each resource can be identified by and accessed at a uniform resource identifier (URI). Using this URI, the resource can be acted upon using various HTTP methods. Typically, the methods are mapped to actions taken on the resource as follows:

HTTP MethodAction
POSTCreate
GETRead
PUTUpdate
DeleteDelete

For example, to get a collection of lists you send a GET request to the Lists resource, which is at http://live.everlytic.net/api/2.0/lists. As GET is the default HTTP Method for browsers, you can do this in your browser. Just click on the following link: http://live.everlytic.net/api/2.0/lists.

You should be prompted to enter a username and password. This is the username and API Key provided to you. Enter these and click OK. If everything went well, you should see the List collection in JSON, and you would have made your first successful REST request.

Parsing Responses

Responses are returned in either JSON or XML. You can change the format of the response by passing an Accept: application/json or Accept: application/xml header along with your request. Most languages have parsers built in for these formats, or have libraries available that can do the parsing for you.

The response is organized into the links, collection and item sections.

The Links Section

REST Web Services are meant to be self-documenting. That is, the client should be able to figure out how to navigate and use the API just by using it. The Everlytic API achieves this by adding a links section to each response. These links conform to the specifications set out in RFC-4287. Some of the links you will see are:

RelationTitleDescription
selfSelfThe URI of the resource you're currently viewing.
homeHomeThe base URI of the API.
nextNextThe next page of the collection.
prevPreviousThe previous page of the collection.
collectionListEntityThe collection the entity is part of.

The Collection Section

The response will contain a collection section if you requested a collection resource. By default, collections are limited to 100 items. In the case of larger collections, links to the rest of the items are provided in the Links section.

Each item in a collection contains an href property which specifies the URI for that item. The data property of the item will contain the actual data of the item.

The data property of an item is not guaranteed to contain all of an item's data. In some cases a summarized version of an item is returned in collections. It is essential to retrieve the item using it's href property to get all of the data.

The Item Section

If you requested a specific entity of a collection by specifying the ID of the entity, the response will contain an item section containing the full details of the requested entity.

Acting on Resources

Reading Resource

To read a resource, you need to execute a GET request on its URI. The following request will retrieve a list of your contacts: GET http://live.everlytic.net/api/2.0/contacts.

In the Links section of the results there will be URIs of other relevant resources such as the URIs of single contacts such as GET http://live.everlytic.net/api/2.0/contacts/123.

Updating a Resource

Updating a resource is similar to creating a resource, with the exception that you're using the PUT method instead of POST, and you'll be using the URI of the entity that you are updating, not the collection.

For example, to update the contact with ID 3, you'll PUT to http://live.everlytic.net/api/2.0/contacts/3, with the fields to be modified URL-encoded in the body of the request. We only support partial updates, using the PUT method, and as such the PATCH method isn't supported.

Other Actions

Working with REST resources can sometimes be confusing because you only have the HTTP verbs (like GET, POST, PUT, DELETE) to work with. So how do you perform actions not defined by these verbs? With a SOAP or XML-RPC interface you specify any type of action. With REST we need to be a little more creative.

For example, how do you send an email campaign? There's no SEND HTTP verb. We handle it in two ways:

  1. You can update the messages' send property to true. Emails don't have a Send property, but updating it to true tells the system that you want to send the email.
  2. The other way is to create a 'send email' action for the message by making a POST request to http://live.everlytic.net/api/2.0/email_actions/$messageId. Just replace $messageId with the ID of the message you want to send.

Passing Data

POST and PUT requests require the client to send data to the API. The API accepts data in three different formats: JSON, XML and URL-encoded form data. The default is form data. To change this, add a Content-Type header to your request:

 

If you're unsure about the format or of the data to pass, refer to a response from the API as reference.

JSON

To send data using JSON, the request should be accompanied by the Content-Type: application/json header.

XML

URL Encoded Form data is the default way in which browsers send data to servers. It's also the default format in which the API accepts data. It's relatively easy to use for simple data sets, but requires some manipulation for complex types such as arrays and objects.

A simple example is:

firstname=John&lastname=Smith

Arrays are a bit more tricky:

 

They should be encoded as:

list[]=element1&list[]=element2

Objects follow the same general concept as Arrays:

Objects should be encoded as:

resource[firstname]=John&resource[lastname]=Smith
Translate »