Primeros pasos

Escribir y testear las aplicaciones que quieras será muy fácil debido a que nuestra API está basada en los principios REST. Esto significa que podrás usar tu navegador para acceder a las URLs e incluso utilizar cualquier cliente HTTP y lenguaje de programación para interactuar con nuestra API Hipermedia.

Autenticación y API Key

Todos los requests realizados a la API requieren que el usuario incluya su API Key.

Cómo obtener tu API Key

Para poder utilizar todos los servicios de nuestra API necesitarás contar con tu API Key, la cual debe ser incluida en cada request. Se trata de un código alfanumérico asociado a tu cuenta de Doppler.

Puedes obtener tu API Key desde el Panel de Control, en la sección de Preferencias Avanzadas. Una vez que la tengas, podrás comenzar a disfrutar de todos los beneficios de la API.

Cómo utilizar tu API Key

Gracias a la API Key podrás hacer requests en nombre de un usuario determinado.

GET https://restapi.fromdoppler.com?access_token=...

Puedes incluir la API Key dentro de los parámetros de consulta, tal como se muestra arriba, aunque el enfoque más limpio y seguro es incluirla en el header de autorización. Así como aparece en el ejemplo de abajo:

GET https://restapi.fromdoppler.com

Authorization: token OAUTH-TOKEN

Usos Básicos

Cómo solicitar un recurso

¡Ya sabes todo lo que necesitas para dar tus primeros pasos! Es momento de comenzar. Aquí te mostramos un ejemplo práctico de cómo realizar un request. ¡Presta atención!

Imagina que tienes una cuenta con este usuario: test@test.com y tu API Key es 22495B800297B754C6EF66FA2C5C1902. Lo que quieres es obtener todas las Listas que has creado y para ello, deberás preparar el siguiente HTTP request:

GET https://restapi.fromdoppler.com/accounts/test@test.com/lists

Authorization: token 22495B800297B754C6EF66FA2C5C1902

Esta es la respuesta que te devolverá nuestra API:

Status Code: 200 OK
Content-Length: 2130
Content-Type: application/json; charset=utf-8; profile=https://restapi.fromdoppler.com/schemas/list-collection-page.json
Date: Tue, 01 Sep 2015 15:16:47 GMT

{
  "items": [
    {
      "listId": 509702,
      "name": "My First List",
      "currentStatus": "ready",
      "subscribersCount": 0,
      "creationDate": "2015-09-01T15:16:32.75+00:00",
      "_links": [
        {
          "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509702",
          "description": "Get list",
          "rel": "https://restapi.fromdoppler.com/docs/rels/get-list"
        },
        {
          "href": "/accounts/test@test.com/lists/509702",
          "description": "Edit a list",
          "rel": "https://restapi.fromdoppler.com/docs/rels/edit-list"
        },
        {
          "href": "/accounts/test@test.com/lists/509702",
          "description": "Delete a list",
          "rel": "https://restapi.fromdoppler.com/docs/rels/delete-list"
        },
        {
          "href": "/accounts/test@test.com/lists/509702/subscribers",
          "description": "Get subscribers of a list",
          "rel": "https://restapi.fromdoppler.com/docs/rels/get-subscribers-collection"
        },
        {
          "href": "/accounts/test@test.com/lists/509702/subscribers/import",
          "description": "Import subscribers",
          "rel": "https://restapi.fromdoppler.com/docs/rels/import-subscribers"
        },
        {
          "href": "/accounts/test@test.com/lists/509702/subscribers",
          "description": "Associate subscriber",
          "rel": "https://restapi.fromdoppler.com/docs/rels/associate-subscriber"
        }
      ]
    }
  ],
  "pageSize": 20,
  "itemsCount": 1,
  "currentPage": 1,
  "pagesCount": 1,
  "_links": [
    {
      "href": "/accounts/test@test.com",
      "description": "Get account home",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-account-home"
    },
    {
      "href": "/accounts/test@test.com/lists",
      "description": "Create a list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/create-list"
    },
    {
      "href": "/accounts/test@test.com/lists",
      "description": "Single page",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-lists-collection first last self"
    }
  ]
}

Como puedes observar, esta respuesta contiene un máximo de 20 ítems, cada uno de los cuales representa una Lista con su respectivo ID, nombre, estado y links para realizar posibles acciones, por ejemplo, eliminarla. Aquí puedes verlo en detalle: rel=https://restapi.fromdoppler.com/docs/rels/delete-list.

Cómo crear un recurso

Para dar origen a una nueva Lista llamada por ejemplo “My second List” debes enviar el siguiente request:

POST https://restapi.fromdoppler.com/accounts/test@test.com/lists

Authorization: token 22495B800297B754C6EF66FA2C5C1902
Content-Type: application/json

{
  "name": "My Second List"
}

A lo que la API de Doppler retornará lo siguiente:

Status Code: 201 Created
Content-Length: 1559
Content-Type: application/json; charset=utf-8; profile=https://restapi.fromdoppler.com/schemas/creation-result.json
Date: Tue, 01 Sep 2015 16:08:28 GMT
Location: https://restapi.fromdoppler.com/accounts/api_functionaltests@mailinator.com/lists/509719

{
  "createdResourceId": "509719",
  "message": "List successfully created",
  "_links": [
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719",
      "description": "Get list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-list related"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719/subscribers/import",
      "description": "Import subscribers",
      "rel": "https://restapi.fromdoppler.com/docs/rels/import-subscribers"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719/subscribers",
      "description": "Associate subscriber",
      "rel": "https://restapi.fromdoppler.com/docs/rels/associate-subscriber"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719",
      "description": "Delete a list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/delete-list"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719",
      "description": "Edit a list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/edit-list"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists",
      "description": "Get lists collection",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-lists-collection parent"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists",
      "description": "Create a list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/create-list"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com",
      "description": "Get account home",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-account-home"
    }
  ]
}

Esta respuesta representa la creación de un nuevo recurso (Status Code), También incluye el link a la Lista creada (Location y rel=related) y su ID (createdResourceId) así como un conjunto de links para realizar diferentes acciones.

Tareas asincrónicas

Existen algunas acciones que no son realizadas de manera inmediata, como por ejemplo, importar Suscriptores.

Si la propiedad callback está establecida, cuando el proceso de importación finalice, la API ejecutará un POST request contra la URL. En nuestro ejemplo: http://my.own.server.com/my/own/resource.

Este sería el request:

POST https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719/subscribers/import

Authorization: token 22495B800297B754C6EF66FA2C5C1902
Content-Type: application/json

{
  "fields": [],
  "items": [ 
    { "email": "test@test.com" }
  ],
  "callback": "http://my.own.server.com/my/own/resource"
}

Y esta la respuesta de la API:

Status Code: 202 Accepted
Content-Length: 850
Content-Type: application/json; charset=utf-8; profile=https://restapi.fromdoppler.com/schemas/creation-result.json
Date: Tue, 01 Sep 2015 17:48:49 GMT
Location: https://restapi.fromdoppler.com/accounts/test@test.com/tasks/import-2843

{
  "createdResourceId": "import-2843",
  "message": "Import task successfully created",
  "_links": [
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/tasks/import-2843",
      "description": "Get task",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-task related"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719/subscribers",
      "description": "Get subscribers of a list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-subscribers-collection /docs/rels/not-implemented parent"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719",
      "description": "Get list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-list"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com",
      "description": "Get account home",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-account-home"
    }
  ]
}

En el ejemplo aparece Status Code: 202 Accepted. Eso significa que la tarea ha sido aceptada y que está siendo procesada de forma asincrónica.

En este caso, Location, rel=related y createdResourceId hacen referencia a la tarea del recurso creado. Es muy fácil obtener detalles sobre su progreso, para ello debes enviar el siguiente request:

GET https://restapi.fromdoppler.com/accounts/test@test.com/tasks/import-2843

Authorization: token 22495B800297B754C6EF66FA2C5C1902

En este caso, la API retornará lo siguiente:

Status Code: 200 OK
Content-Length: 1336
Content-Type: application/json; charset=utf-8; profile=https://restapi.fromdoppler.com/schemas/task.json
Date: Tue, 01 Sep 2015 18:10:04 GMT

{
  "importDetails": {
    "listId": 509719,
    "contentType": "application/json",
    "deleteCustomFieldsData": false,
    "status": "completed",
    "amountImported": 1,
    "numberOfAttempts": 0,
    "dateLastImported": "2015-09-01T18:09:50.42",
    "processed": 1,
    "invalidEmails": 0,
    "softBounceds": 0,
    "hardBounceds": 0,
    "subscriberBounceds": 0,
    "amountHeadersAndFieldsDontMatch": 0,
    "neverOpenBounceds": 0,
    "updated": 0,
    "newSubscribers": 1,
    "duplicated": 0,
    "unsubscribedByUser": 0,
    "usersInBlackList": 0,
    "duplicatedField": 0
  },
  "taskType": "import",
  "taskId": "import-2844",
  "itemsProcessed": 1,
  "status": "completed",
  "startDate": "2015-09-01T18:09:50.327+00:00",
  "finishDate": "2015-09-01T18:09:50.42+00:00",
  "_links": [
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/tasks/import-2844",
      "description": "Get task",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-task self"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com",
      "description": "Get account home",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-account-home"
    },
    {
      "href": "https://restapi.fromdoppler.com/accounts/test@test.com/lists/509719",
      "description": "Get list",
      "rel": "https://restapi.fromdoppler.com/docs/rels/get-list"
    }
  ]
}

Manejo de errores

¿Algo no anda bien? Chequea estos ejemplos de errores y aprende cómo solucionarlos.

Suponte que has alcanzado el número máximo de Listas permitidas para tu cuenta y quieres crear una nueva. La API te devolverá una respuesta como esta:

{
  "title": "Maximum number of lists reached",
  "status": 400,
  "errorCode": 3,
  "detail": "It reached the maximum number of Lists. Can not create new ones.",
  "type": "https://restapi.fromdoppler.com/docs/errors/400.3-maximum-number-of-lists-reached"
}

Como aparece en ejemplo anterior, el campo type hace referencia a una página donde puedes obtener más información sobre el error en cuestión y la manera de resolverlo. Para conocer el listado completo de posibles problemas, revisa la sección Errores.

Formato de datos y campos

Formato de fecha y hora

El siguiente es un ejemplo de una respuesta de la API vinculada a una Lista de Suscriptores:

{
  "listId": 509702,
  "name": "My First List",
  "currentStatus": "ready",
  "subscribersCount": 0,
  "creationDate": "2015-09-01T15:16:32.75+00:00",
  ...

Como puedes ver, creationDate representa un valor de fecha y hora. Con el fin de evitar ambigüedades, la API expone sus datos utilizando el Coordinated Universal Time (UTC).

Estos son algunos ejemplos de los formatos permitidos: 2015-08-15T09:00+04:00, 2015-05-21T09:00:36-03:00, 2010-01-29T09:00:36.515+00:00 y 2015-01-29T09:00:36Z.

Filtro de fecha y hora

Al solicitar una colección de datos como puede ser el conjunto de Suscriptores Removidos, podrás filtrar la información de acuerdo a un rango de tiempo determinado incluyendo los parámetros from y to.

A la hora de aplicar los filtros es muy importante que prestes atención a las siguientes reglas:

Los valores de fecha y hora deben explicitar el huso horario.
- Válido: ...?from=2015-05-21T09:00:36-03:00&to=2015-01-29T09:00:36Z.
- Inválido: ...?from=2015-05-21T09:00:36&to=2015-01-29T09:00:36.
Si no se incluyen los parámetros mencionados, los filtros no serán aplicados, por lo que se devolverán todos los resultados encontrados.
- ...?from=2015-05-21T09:00:36-03:00&to=2015-01-29T09:00:36Z significa entre 2015-05-21T09:00:36-03:00 y 2015-01-29T09:00:36Z.
- ...?from=2015-05-21T09:00:36-03:00 significa después de 2015-05-21T09:00:36-03:00.
- ...?to=2015-01-29T09:00:36Z quiere decir antes de 2015-01-29T09:00:36Z.
El filtro from es cerrado (incluyente)
- ...?from=2010-01-29T09:00:36.515+00:00 incluye eventos ocurridos exactamente en el momento o después.
El filtro to es abierto (excluyente)
- ...?to=2010-01-29T09:00:36.515+00:00 no incluye eventos ocurridos exactamente en ese momento, sino anteriormente.

Importante: Ten en cuenta que los parámetros en cadenas de consulta deben ser encodeados, por lo tanto, el caracter + deberá ser remplazado por %2B. Por ejemplo, si quieres obtener todas las remociones realizadas después del 1 de enero a las 3 p.m. de Roma, Italia (UTC +2 horas), la URL deberá ser la siguiente: https://restapi.fromdoppler.com/accounts/test@test.com/unsubscribed?from=2015-01-01T03:00%2B02:00.

Valores de solo fecha

Este es el tipo de dato más sencillo de solicitar, para hacerlo deberás utilizar estos formatos: 2015-08-20 y 20150820.

Valores de Campos de Suscriptores

Los Suscriptores tienen un conjunto de valores clave llamados Fields (chequea subscriber.json y field-value.json). Para obtener el listado completo de las definiciones de los campos de la cuenta utiliza el recurso Fields.

Los Fields siempre son cadenas de valores, pero dependiendo del tipo de propiedad adquirirá formatos diferentes:

boolean: true o false (distingue mayúsculas y minúsculas).
number: Una serie de números con o sin punto seguido por otra serie de números. Acepta positivos y negativos.
string: Cualquier valor de texto (400 caracteres como máximo).
date: Acepta cualquier fecha y hora válidas, pero solo almacena la parte fecha. El formato recomendado es yyyy-MM-dd.
gender: M para masculino y F para femenino (distingue mayúsculas y minúsculas).
country: ISO 3166-1 alpha-2 código de país (no distingue mayúsculas ni minúsculas).

Importante: Si durante el proceso de importación de un Suscriptor, un valor no puede analizarse siguiendo las reglas mencionadas, el valor del Field anterior no se cambiará sin advertencia.