Doppler Relay
Regístrate gratis

Primeros Pasos

Como la API se basa en los principios de REST, es muy fácil escribir y probar aplicaciones. Puedes usar tu navegador para acceder a las URLs, y puedes usar prácticamente cualquier cliente HTTP en cualquier lenguaje de programación para interactuar con la API.

Autenticación

Obteniendo una API Key

La mayoría de los servicios de retransmisión requieren llamarlos en nombre de un usuario, por lo que se requiere una API key en cada solicitud.

Usando la API Key

La API key te permite realizar solicitudes a la API en nombre de un usuario.

GET https://api.dopplerrelay.com?api_key=...

Puedes pasar la API Key en los parámetros de consulta como se muestra arriba, pero un enfoque más limpio (y más seguro) es incluirlo en el encabezado Authorization.

GET https://api.dopplerrelay.com

Authorization: Bearer OAUTH-TOKEN

Uso básico

Pidiendo un recurso

Supongamos que tu ID en Doppler Relay es 5, tu API Key es 22495B800297B754C6EF66FA2C5C1902 y quieres obtener la colección de plantillas que has creado.

Por lo tanto, debes preparar la siguiente solicitud HTTP:

GET https://api.dopplerrelay.com/accounts/5/templates

Authorization: Bearer 22495B800297B754C6EF66FA2C5C1902

La API devolverá algo como esto:

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

{
  "items": [
    {
      "from_name": "user",
      "from_email": "test",
      "subject": "Hi!",
      "body": "<p>Hi</p>",
      "name": "Demo",
      "id": "caa9480f-8251-434e-b600-b9b68c346632",
      "last_updated": "2016-06-27T19:34:23+00:00",
      "created_at": "2016-06-27T19:34:23+00:00",
      "_links": [
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Specific template",
          "rel": "/docs/rels/get-template"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632/message",
          "description": "Create and send an email based on a template and a model to populate it",
          "rel": "/docs/rels/create-template-message"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Delete template",
          "rel": "/docs/rels/delete-template"
        },
        {
          "href": "/accounts/5/templates/caa9480f-8251-434e-b600-b9b68c346632",
          "description": "Edit template",
          "rel": "/docs/rels/edit-template"
        }
      ],
      "pageSize": 200,
      "itemsCount": 9,
      "currentPage": 1,
      "pagesCount": 1,
      "_links": [
      {
        "href": "/accounts/5/templates",
        "description": "Collection of templates",
        "rel": "/docs/rels/experimental /docs/rels/get-template-collection self"
      },
      {
        "href": "/accounts/5/templates",
        "description": "Create template",
        "rel": "/docs/rels/create-template"
      },
      {
        "href": "/accounts/5",
        "description": "Account home",
        "rel": "/docs/rels/get-account-home"
      },
      {
        "href": "/",
        "description": "API index",
        "rel": "/docs/rels/get-index"
      }
  ]
    },

Esta respuesta representa una página con un máximo de 20 elementos, cada uno de los cuales representa una plantilla con un ID, el nombre, el estado y los enlaces para posibles acciones en ella, por ejemplo, eliminarla (ver rel=https://api.dopplerrelay.com/docs/rels/delete-template).

Además, la página tiene enlaces a recursos y acciones relacionados, por ejemplo, crear uno nuevo (ver rel=https://api.dopplerrelay.com/docs/rels/create-template).

Creando un recurso

Si quieres crear una nueva plantilla llamada "Mi segunda plantilla", debemos enviar la siguiente solicitud:

POST https://api.dopplerrelay.com/accounts/5/templates

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

{
  "body": "Hello, this is my first Template.",
  "subject": "Test Template",
  "from_email": "[email protected]",
  "name": "Mi segunda plantilla"
}

La API devolverá algo como esto:

Status Code: 201 Created
Content-Length: 1559
Content-Type: application/json; charset=utf-8; profile=https://api.dopplerrelay.com/schemas/creation-result.json
Date: Tue, 01 Sep 2015 16:08:28 GMT
Location: https://api.dopplerrelay.com/accounts/5/templates/509719

{
  "createdResourceId": "509719",
  "message": "Template successfully created",
  "_links": [
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Specific template",
      "rel": "/docs/rels/get-template related"
    },
    {
      "href": "/accounts/5/templates",
      "description": "Create template",
      "rel": "/docs/rels/create-template self"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Delete template",
      "rel": "/docs/rels/delete-template"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab",
      "description": "Edit template",
      "rel": "/docs/rels/edit-template"
    },
    {
      "href": "/accounts/5/templates",
      "description": "Collection of templates",
      "rel": "/docs/rels/experimental /docs/rels/get-template-collection"
    },
    {
      "href": "/accounts/5/templates/6cfe366a-ba4c-448d-bd08-0442c20769ab/message",
      "description": "Create and send an email based on a template and a model to populate it",
      "rel": "/docs/rels/create-template-message"
    },
    {
      "href": "/accounts/5",
      "description": "Account home",
      "rel": "/docs/rels/get-account-home"
    },
    {
      "href": "/",
      "description": "API index",
      "rel": "/docs/rels/get-index"
    }
  ]
}

Esta respuesta representa una creación de recursos (ver Status Code), incluye el enlace a la plantilla creada (ve el encabezado Location y el enlace rel=related) y el ID (ve la propiedad createdResourceId). Y, por supuesto, un gran conjunto de enlaces de acciones relacionadas.

Tratando con errores

Supongamos que creas una nueva plantilla en tu cuenta sin el campo obligatorio from_email, nuestra API devolverá algo como esto:

{
  "title": "Validation error",
  "status": 400,
  "errorCode": 1,
  "detail": "Validation error validating `/schemas/template.json` for ``. See `errors` field for more details.",
  "errors": [
    {
      "key": "from_email",
      "detail": "The from_email field is required."
    }
  ],
  "type": "/docs/errors/400.1-validation-error",
  "_links": [
   {
     "href": "/accounts/{accountId:int}",
     "description": "Account home",
     "rel": "/docs/rels/get-account-home"
   }
  ]
}

Revisa el campo type, se refiere a una página donde puedes obtener más información sobre el error y cómo resolverlo. Consulta la sección Errores para la lista completa de los posibles tipos de problemas.

Formato de datos especiales y fechas

Valores de fecha y hora

La siguiente es una representación de una solicitud de reporte, a partir de una respuesta de la API:

{
  "user_id": 3,
  "name": "My First template",
  "processed": true,
  "start_date": "2015-09-01T15:16:32.75+00:00",
  "end_date": "2015-09-02T15:16:32.75+00:00",
  "filter": "test"
  ...

Como puedes ver, los campos start_date y end_date representan los valores de fecha y hora. Para evitar ambigüedades, la API expone los valores de fecha y hora utilizando el Tiempo Universal Coordinado (UTC) y haciendo que el desplazamiento sea explícito (+00:00).

Se requiere una zona horaria explícita en las entradas, por ejemplo, estos son valores de fecha y hora aceptados: 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.

Filtrado de fecha y hora

Al solicitar algunas colecciones, por ejemplo datos agregados entregas (para estadísticas), se permite filtrar por un intervalo de tiempo dando los parámetros from y to siguiendo las siguientes reglas: