|Payload||URL encoded form data|
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:
For example, to get a collection of lists you send a
GET request to the Lists resource, which is at
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.
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.
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:
|self||Self||The URI of the resource you're currently viewing.|
|home||Home||The base URI of the API.|
|next||Next||The next page of the collection.|
|prev||Previous||The previous page of the collection.|
|collection||ListEntity||The collection the entity is part of.|
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.
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.
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
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
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.
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:
true. Emails don't have a Send property, but updating it to
truetells the system that you want to send the email.
http://live.everlytic.net/api/2.0/email_actions/$messageId. Just replace $messageId with the ID of the message you want to send.
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.
To send data using JSON, the request should be accompanied by the
Content-Type: application/json header.
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:
Arrays are a bit more tricky:
collection = array(
0 => 'element1',
1 => 'element2',
They should be encoded as:
Objects follow the same general concept as Arrays:
resource = new Person
resource->firstname = 'John'
resource->lastname = 'Smith'
Objects should be encoded as: