Autocosmos API v3

Introdución

Bienvenido a la documentación de la API de Autocosmos.
Si estás buscando un JSON, y no te funcionó escribir "swagger" en la URL, lo que estás buscando es openapi.json (aka swagger.json).
Si eres un developer, aunque esta página sea texto (no es código) y parezca largo y aburrido, dale una leída (atenta y paciente) porque te ahorrarás bastante tiempo.
Si no eres developer la introducción es más que suficiente.

Para tener acceso a nuestra API, lo primero que tienes que hacer es solicitar tu AppKey y AppSecret. Puedes enviarnos un mail a developers@autocosmos.com contándonos un poco de tu app y proveyendo:

  • URL publica para que podamos verificar de que app se trata.
  • E-mail address del responsable/grupo que será nuestro contacto para comunicaciones, exquisitamente técnicas, sobre el uso de la API.
Nosotros nos contactaremos con uno de nuestros comerciales para verificar que permisos tendrás (creación de subscriptions, publicación, acceso avanzado a la info de catálogo etc.) y luego te enviaremos las credenciales en dos mails separados.

Consideramos la API como una cuestión exclusiva entre developers así que, si necesitas ayuda, siempre nos encuentras en developers@autocosmos.com.
Si te es posible, invita, con mail en copia, solo a técnicos; evita agregar gente sin conocimiento de programación. Si piensas que no te es posible tener un contacto entre developers solamente, por favor, no escribas directamente a nuestro email y pedile, a quien te lo impide, de seguir los canales correspondientes pasando por los servicios correspondientes.
Si estás leyendo este párrafo, y no eres un developer, ten en cuenta que, en los mail que nos intercambiaremos, usaremos frases como la siguiente:
El 401, en un method no idempotent, es porque no estás recalculando el HMAC o repetiste el mismo request en un tiempo inferior de la precisión que usaste para asignar el header Date o X-ACS-Date.

Y ahora vamos a lo nuestro...

Filosofía

Como te darás cuenta hemos tratado, nuevamente, de implementar una API RESTful. Creemos firmemente que internet nació ya teniendo todo lo necesario para el intercambio de información y los developers hemos hecho lio por muchos años inventándonos sistemas de comunicación por arriba de algo que ya tiene todo. Aclaramos esto porque tienes muy pocas chances de usar nuestra API, de forma correcta, si no le prestas atención a los HTTP-methods, los status-codes, los headers (incluyendo los headers de cache) y los MIME-Types.

Para nosotros un algoritmo debería estar en condición de usar/navegar una API así como un usuario navega una página. Esto significa que no deberías tener, en tu código, muchas paths grabadas y menos deberías tener nuestros IDs. Manteniendo firmes los models en entrada y salida, y los nombres de las rel (relationships), queremos ser libres de cambiar la organización de la API así como los IDs; si usaste nuestras anteriores APIs ya "sufriste" cambios de URLs y lo más probable es que vuelva a pasar.

Tenemos, en nuestro corazón, el espíritu de los viejos hackers (de cuando el término 'hacker' se usaba para los buenos que mejoraban algoritmos y donaban las mejoras al mundo) y por ese motivo te pedimos ayuda. Siempre manteniéndonos en el uso de nuestra API, nos esperamos que te comuniques con nosotros, nos cuentes los problemas, vueltas "raras" que tienes que dar, cosas que sientes que te faltan, IDs que te sientes obligado a guardar, URLs que necesitas guardar etc. etc. En las escuelas que hayas frecuentado, a ti también, te habrá faltado la materia "lectura de bola de cristal" así que estamos seguros de que nos vas a entender. No asumas que tu consulta molesta, deja que te lo digamos nosotros si sentimos que es el caso.

Base URL

La base URL está así compuesta: {scheme}://api.autocosmos.{top-level domain}/v3
En todos los países donde se está utilizando actualmente la API el {scheme} es siempre: https
El {top-level domain} cambia según el País con el cual interactúes:

  • Argentina: com.ar
  • Chile: cl
  • Colombia: com.co
  • Ecuador: com.ec
  • Mexico: com.mx
  • Perú: com.pe
La path de la URL es case-insensitive.
Los valores de los parámetros del query-string, cuando usado para búsqueda de texto, serán usado como case-insensitive.

Los HTTP-Methods

Ya que en pasado hemos recibido preguntas sobre el tema, no damos por sentado que sepas como usamos/interpretamos todos los HTTP-Methods en nuestra API, así que te lo contamos.
  • GET
    Con este método vienes a leer/buscar información. Si la información no existe, o no existe para ti, recibirás un 404.
    En el caso vengas a buscar una lista es probable que recibas una lista vacía en lugar que un 404. Para entidades por la cuales te damos el ETag podrás combinar el GET con el header If-None-Match.
  • POST
    Con este método "creas cosas", que no existían o pides que se ejecuten acciones que "crearán cosas".
    Cuando creas algo te devolveremos un 201 y el header Location para que sepas donde está la entidad en nuestra API. A diferencia de las versiones anteriores de la API, con el 201 también te devolveremos el estado de la entidad que creaste con el mismo payload devuelto para el GET. En el caso que el POST implique una operación asincrónica, te contestaremos con un 202 y el Location donde ir a ver si/cuando la operación se completa.
    Si te faltan permisos te contestaremos con un 401 o un 403 dependiendo si te faltan permisos de uso de la API o si no tienes acceso a crear el dato (ej: no tienes acceso a publicar para una agencia específica).
  • PUT
    Con este método "modificas cosas" accediendo, a toda la información modificable, en el mismo momento.
    Si la modificación va a buen fin, te devolveremos un 200 y el estado de la entidad que modificaste con el mismo payload devuelto para el GET. Para entidades por la cuales te damos el ETag podrás combinar el PUT con el header If-Match.
  • PATCH
    Con este método "modificas parcialmente cosas".
    Para esta versión de la API aún no le dimos soporte al JSON Patch (application/patch+json) así que encontrarás varios PATCHes que basicamente te permiten cambios de estado o variar solo muy poca info de entidades más complejas. Así como para el PUT, también en este caso, te devolveremos un 200 y el estado de la entidad que modificaste con el mismo payload devuelto para el GET. Cabe destacar que también usamos el PATCH en acciones que terminan dejando una entidad en un estado por el cual ya no tienes más acceso; en ese caso te devolveremos un 204. Para entidades por la cuales te damos el ETag podrás combinar el PATCH con el header If-Match.
  • DELETE
    Con este método "eliminas cosas".
    No siendo más accesible la información, si la operación termina bien, te devolveremos un 204.
  • OPTIONS
    Con este método podrá conocer que métodos tienes permitidos para una determinada path.
    En en el header Allow, del response, tendrás la lista de methods que puedes usar.
    Lo bueno de OPTIONS es que, si tu app no tiene acceso a un método, te lo dice de buena manera. Por ejemplo, tu app puede acceder a la lista de agencias pero no tener permiso de creación de las mismas, entonces el OPTIONS solo te listará el GET sin necesidad que intentes el POST y recibas tú 401.
  • HEAD
    Podrás usar este método con las entidades por la cuales te brindamos el ETag.
    También se puede usar el HEAD en combinación con el header If-None-Match para conocer si una entidad fue modificada por algunos de nuestros procesos (bots).
Los methods idempotent son GET, OPTIONS, HEAD, para todos los otros HTTP-methods hay un caso especial por el cual es posible que recibas un 401.
Quien tiene pelo blanco sabe del famoso MITM attack. Si repites el mismo identico request non-idempotent en un tiempo muy corto, recibirás un hermoso 401 cuyo content te explicará el problema. Te aclaramos esto porque hemos notado, en nuestro log, que para algunas apps no es raro que esto ocurra así que queremos explicarte que está haciendo tu código si recibes un 401 con escrito "Request repetido dentro de un lapso corto". En la authentication verás que es practicamente imposible que un request se repita ya que es obligatorio el header Date, o X-ACS-Date, que además son parte de la authentication. Si ves un 401 con escrito "Request repetido dentro de un lapso corto" significa que entro 1" estás repitiendo el mismo request (3 o 4 activaciones de la misma publicación por ejemplo) o, peor aún, estás enviando el mismo request sin cambiar el timestamp y, por ende, sin recalcular el HMAC. La impresión que tendrás es que, si bien recibiste un 401, la operación se llevó a cabo mientras la realidad es que al primer request la operación se hizo correctamente y en las repeticiones recibiste el 401. Si ves un 401 con escrito "Request repetido dentro de un lapso corto", por favor, revisa que está haciendo tu código o que le estás permitiendo hacer, a tu usuario, con los buttons de activar/suspender/publicar etc. La otra posibilidad es que estés asignando el timestamp hasta el minuto, en lugar que hasta los segundos, y el request entra en la tolerancia de falta de sincronización entre servers.

Headers

Ya sabes que son los headers de un request/response así que, en esta sección sólo queremos poner un poco de énfasis en algunos.

Headers en el request
Más allá de los headers Authorization, Digest, Date y X-ACS-Date, que verás para la autenticación, hay otros headers que quisiéramos que conozcas, y si te parece el caso, uses en tus requests.
  • Accept
    En los últimos años, y no creas que son muchos, se perdió la costumbre de prestar atención a este header ya que application/json se volvió casi una constante.
    Si ya usaste nuestras APIs sabes que para nosotros no es una constante y sigue no siéndolo como verás en los MIME types.
  • If-Match
    Con la V3 de la API hicimos público el ETag de algunas entidades. El header If-Match, en nuestra API, te evitará modificar (PUT, PATCH, DELETE) entidades de las cuales ya no tienes un estado actualizado. Si quieres leer más sobre este header y el impacto de usarlo, ingresa a la W3C.
  • If-None-Match
    A diferencia del If-Match, que en nuestra API te previene modificaciones de objetos stale, el If-None-Match te previene pedir información que ya tienes actualizada de tu lado. En nuestra API, podrás usar el If-None-Match con los methods idempotent (GET y HEAD siempre y cuando la entidad tiene ETag). Si quieres leer más sobre este header accede a la W3C.

Headers en el response
  • Location
    Cuando creas algo o envías un comando para que algo se agregue al sistema, te enviaremos, en el header Location la ubicación donde puedes verificar ese algo en nuestra API. Hay sólo unos pocos casos en los cuales es posible que te devolvamos una URL externa a la API de Autocosmos y lo verás en la documentación de los endpoints.
  • ETag
    Como dicho anteriormente, con la V3 de la API hicimos público el ETag de algunas entidades. Si realmente crees que tienes que guardar algo nuestro en tu sistema ese algo es el ETag especialemnte de las publicaciones. El ETag es una especie de Timestamp de la ultima modificación o un ID de la versión de estado de esa entidad, o combinación de los dos. Si quieres leer más sobre este header puedes hacerlo en la W3C.
    Queremos que notes que el ETag es siempre double quotes enclosed; es importante que lo notes por si quieres usarlo en If-Match y/o If-None-Match.
  • Cache-Control
    La cache es esa cosa rara que varios programadores piensan que sirve para que las cosas vayan más rápidas... hasta que están del otro lado de la trichera.
    Seguramente nos recordamos de la cache cuando nuestro interlocutor es un browser, nos recordamos de la cache cuando estamos en un server y queremos balancear el uso de los recursos para que niguno explote, pero muy pocas veces nos recordamos de los headers de cache cuando nuestro interlocutor es una API.
    Por otro lado es verdad que el Cache-Control, en el response, es como una botella con un mensaje tirada al Océano Pacífico. Muchas veces confiamos más en el sentido común, de los programadores que usan nuestras APIs, que en la utilidad de enviarles headers de cache.
    A pesar que nadie te obliga a respetar el Cache-Control que te enviamos, así como lo respectan los browsers, nos gustaría que por lo menos intentes prestarle un poco de atención; es poco útil, para ambas partes, que vengas a buscar una lista completa de marcas y modelos de autos cada 600ms.

MIME types

Nuestras APIs soportan tipos adiccionales de calidad/formato de información que se podrán pedir según el endpoint que se esté usando (especificaciones de la W3C).
Las motivaciones son:

  1. Quien tiene acceso a la información técnica del catálogo accede a los mismos endpoints de quien los usa solo para consultas para publicar.
  2. Si le preguntas a quien paga la factura de los servicios que usas, descubrirás que uno de los items es: bandwidth
Si lo que necesitas es buscar el estado (activo/suspendido) de una publicación, ¿para qué pedir un JSON que contiene toda la información?
La diferencia, en término de bytes que viajan por la net, parece poca hasta que no se multiplique por miles cada segundo de las 24 horas del día y los 365/6 días del año.

Nuestros mime-type son:

  • vnd.autocosmos.entry Entidad/Objeto completo con casi todas sus propiedades.
  • vnd.autocosmos.ref Referencia a una entidad/objeto (un mínimo de información para identificarlo).
  • vnd.autocosmos.ex-entry Entidad/Objeto extendido con propiedades reservadas a acuerdos especiales.

En la mayoría de los casos, en el HTTP-Header Accept nos enviarás application/json (equivalente a application/vnd.autocosmos.entry+json).

En algún caso podrás enviarnos el HTTP-Header con Accept: application/vnd.autocosmos.ref+json, si solo estás interesado en tener referencia/s a objetos y su descripción breve (por ejemplo en requests que devuelven listas y solo necesitas una referencia para luego usarla en otro request).

En el caso tengas un acuerdo de acceso avanzado de la información (por ejemplo a las fichas técnicas y equipamiento de los autos) podrás usar el HTTP-Header Accept: application/vnd.autocosmos.ex-entry+json.

En el caso que el Media Type no esté soportado, o no tengas el permiso de usarlo para un endpoint específico, la API auto-resuelve con el mejor Media Type disponible y más cercano al formato que pediste.

Status Codes

Si está la palabra "code" es porque a los informáticos nos gustaba poco analizar frases y necesitabamos algo estándar y simple para entender lo que pasó al enviar un request. Si bien los más conocidos en la WEB son el 200 y el 404, en realidad, la lista usada en la WEB, fué siempre más extensa. Las antiguas escrituras citan unos 40 status codes y, si te fijas bien, verás que la mayoría son de anomalías. En los "últimos años" hasta aparecieron domains, como https://httpstatuses.com/ que solo exponen HTTP status codes. Hemos visto APIs que devuelven 200 y un JSON tipo {"error":"Hubo un problema al grabar"} y consideramos que, en ese caso, más que RESTful estamos en presencia de un "restfulness" del programador.
Ya has visto que usamos varios de los status-codes y, en los endpoints, verás que te devolvemos en cada caso.
En esta sección queremos enfatizar un status-code en particular.

El 503
Por más que existan layers, backups, replica, failover, fallback etc. los sistemas, de cualquier naturaleza, fallan, o mejor dicho, porque los sistemas fallan existen tantas palabras/técnicas para apaciguar la situación. Si tenemos suerte, los sistemas, nos avisan y si no tenemos suerte no nos avisan (como cuando se corta internet justo en el medio de un push). El 503 es un sistema que te está avisando un problema y para eso fué definido desde los albores del HTTP.
Autocosmos palpita en el cloud, hace muchos años, y lo que hemos abrazado desde el inicio es la platform as a service en lugar que infrastructure as a service. Eso significa que, si bien sabemos que de algún lado deben haber algunas máquinas con algunas CPU y algún disco, no tenemos la menor idea de donde están ni quien las gestionan, solo usamos servicios y deployamos ejecutables o hasta deployamos pequeños cachos de código. Te contamos esto porque hemos aprendido que hay que tener en cuenta que los sistemas fallan. En nuestras APIs internas tratamos siempre de tener en cuenta que la otra API puede fallar.
En la API V2 teníamos una serie de endpoints asincrónicos que justamente estaban para que tu no te preocupes mucho de los 5xx, pero hemos notado que, con el pasar de los años, esos endpoints cayeron en desuso tanto que, en la V3, directamente brindamos solo endpoints sincrónicos.
Querido compañero developer, ten en cuenta que los 5xx son una realidad. Si vienes a leer (GET) y te llega un 5xx, usa el estado que tienes como si fuese la realidad actual o usa el último estado que recibiste si aún los tienes en cache. Si vienes a escribir (POST, PUT, PATCH, DELETE), y te llega un 5xx, graba las operaciones en secuencia en un sistema de queues y vuelve a intentar las operaciones luego de unos minutos. Abraza la consistencia eventual (eventual consistency) sin distanciamiento social.
¿Te parece mucho? eso es exactamente lo que hacemos en Autocosmos, por ejemplo, con las fotos de las publicaciones que nos enviarás:
  • si tu server nos contesta con un 404 la foto no existe así que la borramos de la publicación.
  • si tu server nos contesta con un 5xx haremos otros dos intentos, distanciados cada 15 minutos, antes de eliminar la foto en la publicación.
Si quieres enojarte frente un 5xx no hay drama, nos pasa a todos, pero trata de usar tu energía para pensar como resolver el problema en tu sistema porque los 5xx son, y seguirán siendo, una realidad; ya sabes adonde encontrarnos para charlar del tema, si quieres.

Authentication y Authorization

Para este tema tenemos una sección a parte (ver sub menú) ya que será tu primer escollo a superar. Aquí te anticipamos que la authentication es basada en HMAC y solo necesitarás el AppSecret para calcular tu credencial de acceso. Para la authorization hay dos niveles (para intentar ser breves):

  1. Los permisos que se concedieron a tu app para interactuar con la API.
  2. Los permisos que tu app tiene en cada suscription (en cada agencia/concesionaria).
Si hay problemas con tu implementación del cálculo del HMAC, o tu app no tiene determinados permisos con la API, recibirás un 401. Si tu app no tiene suficientes permisos en una subscription (una agencia), teniendo suerte recibirás un 403 mientras que, si no tienes suerte, simplemente pensarás que algo no funciona en la API de Autocosmos porque no está la información que te esperas en los responses.

Ten en cuenta que, por lo general, en una subscription tendrás acceso solo a lo que generaste desde la API y a los derivados de lo que generaste desde la API. Por ejemplo, si consultas las visitas de una subscription, solo verás las visitas a las publicaciones que creaste desde la API, mientras que la subscription puede tener más visitas a publicaciones que un usuario creó desde Autocosmos o que creó usando otra app.

Donde están los IDs y el nefasto problema del mapping entre identificadores.

Los IDs son artefactos que los informáticos necesitamos. Un nene de dos años reconoce su "amado juguete" en el medio de otros cientos sin leer su barcode o su QR.
Cada sistema tiene sus IDs; hay quien usa RDBMS con nefastas claves compuestas (peor involucradas con el negocio), hay quien usa aún más nefastos autonuméricos, hay quien abraza los UUID/GUID y también hay quien hereda sistemas con persistencia monolítica y quisiera romper todo y abrazar la persistencia desparramada (widespread persistence).
En Autocosmos usamos IDs pero no nos gusta usar lo que tenemos, así que menos nos gusta que tu uses nuestros IDs. Para la misma entidad tenemos varias formas de identificarla y quien usa/usó nuestras APIs sabe que también somos capaces de cambiar la forma pública de identificar algo que consideramos nuestro exclusivo dominio.

Quien usa/usó la API, casi exclusivamente, para consultar precios o información de catálogo, AFAIK no tuvo mayores problemas de identificación de entidades así que dedicamos nuestros esfuerzos a las apps de replicación/multi-posting de publicaciones.

Donde pudimos sumamos estándares internacionales de identificar cosas. Lo verás, por ejemplos, en las monedas y en las regiones donde ya hay ISO que nos ayudan a no pelear entre developers por como identificar algo.
Por lo general, en nuestras APIs, tienes que pensar en recursos y no tienes que pensar en IDs.
Si te pedimos un ID nuestro, sin haberte enviado la URI nosotros, es porque nos equivocamos y a la próxima versión de la API intentaremos corregirlo (por favor, notifícanos donde te pedimos un ID nuestro sin proveerte la URI completa en algún endpoint).
Uno de los objetivos, en el cual concentramos nuestros esfuerzos, es que usemos identificadores comunes o directamente uses tus IDs. Por ese motivo las personas y las cuentas las identificamos con su e-mail, para las publicaciones de autos directamente trabajarás con tu ID y donde se pueda usaremos ISOs o nombres reconocidos en cada país.

Parece todo hermoso, pero no... aún quedan cabos sueltos.
Las ciudades son un punto de choque y sabemos que es un problema.
Los nombres de las marcas (aka make) son bastante estables como para que no hayan problemas pero cuando bajamos de un nivel y vamos a los nombres de modelos (aka model) de autos ya empiezan los dolores y ni hablar cuando bajamos un nivel más y vamos a los nombres de las versiones de autos (aka trim).
Para apaciguar el problema de nombre de versión (trim) en las publicaciones, permitimos que sea casi texto libre en los autos usados (aunque eso implique perder un poco de calidad de publicación ya que no estará la información técnica que nuestro equipo de catálogo mantiene actualizada). Para autos nuevos, aún no está permitido publicar un auto sin que coincida exactamente con una versión (trim) de la cual Autocosmos posee toda la info. técnica.
Con la identificación de modelos (model) de autos, querido compañero developer, tendremos choques pocos placenteros.

En lo que nos sea posible, queremos evitarte mappings de IDs así que en esta versión de la API brindamos nuevos endpoints que esperamos te eviten, por completo, pensar en dichos mappings.
Cuando te pedimos información de ubicaciones (estado/provincia/región, ciudad), de características del auto/carro/coche y monedas, lo que te pediremos es un string que termina soportando varios formatos desde partes de nombre, nombre común, ISOs, URLs de nuestra API (absoluta o relativa), hasta IDs (nuestros).

¿Cómo elegir como asignar esas propiedades?
En esta versión de la API hemos implementado lo que esperamos se transforme en tu compañero en la lucha contra el mapping y el escaneo de listados completos: el bestmatch.
En varias entidades encontrarás un endpoint bestmatch y no te preocupes por usarlo en todas las entidades porque, cuando publiques un auto o una ubicación (región/ciudad), nosotros nos encargaremos de usar el algoritmo de bestmatch para encontrar la entidad correcta.
El bestmatch que tal vez te seas más útil es el de versiones ya que podrás buscar un marca+modelo+versión teniendo el nombre de la marca, algo del modelo (una parte del nombre por ejemplo), un año, y alguna característica técnica del auto, hasta sin tener absolutamente nada del nombre de la versión. No siempre tendrás suerte que logremos encontrar la versión por la cual tengamos toda la info. técnica pero igual, ese endpoint, te brindará la info. que podrás usar en una nueva publicación (si no hay match de versión no podrás publicar autos nuevos y si no hay match de modelo directamente no podrás publicar).
Si publicas un auto, sin usar antes el bestmatch de versiones, nos encargaremos nosotros de usar la información que brindaste en la publicación y si no encontramos lo mínimo necesario recibirás un 400.

La propiedad _links y sus rel.

_links es un tipo de hyperlinking entre recursos de la API. En casi la totalidad de los responses verás que los objetos tienen la propiedad _links. _links es un objeto cuyas propiedades representan acciones con el recurso que la declara. Cada propiedad, de _links, es un objeto similar al tag <a> de HTML (de allí vienen prácticamente la totalidad de los nombres de las propiedades). 

"_links": {
    "self": {
        "href": "/v3/agencias/franco@superautos.com"
    },
    "change": {
        "href": "/v3/agencias/franco@superautos.com",
        "method": "PUT"
    },
    "release": {
        "href": "/v3/agencias/franco@superautos.com/desasociar",
        "method": "PATCH"
    }
}
Este ejemplo representa el objeto _links de una agencia.
La rel (propiedad de _links) con nombre self es el hyperlink para acceder a la entidad agencia con todas sus propiedades; el href es la path relativa de la API.
La rel change es el hyperlink para modificar la entidad agencia; el href es la path relativa de la API y method es el HTTP-Method a usar para el change.
La rel release es el hyperlink para desasociar/desvincular la agencia de tu app; el href es la path relativa de la API y method es el HTTP-Method a usar para el release.
Así como para el tag <a> de HTML, también en las rel, si no se especifica el method, se trata del GET.

Supongamos que quieres acceder a las consultas recibidas por la agencia cuyo mail del administrador es franco@superautos.com. Verás que el href, del recurso que te damos, es : /v3/consultas/franco@superautos.com.
Nota que la URL es simple y no tiene nada en el query-string. La propiedad _links del recurso /v3/consultas/franco@superautos.com puede lucir como la siguiente: 

"_links": {
    "self": {
        "href": "/v3/consultas/franco@superautos.com?desde=2021-09-23&hasta=2021-10-23&pagina=1"
    },
    "search": {
        "href": "/v3/consultas/franco@superautos.com?operador={operador}&externalid={externalid}&desde={desde}&hasta={hasta}&pagina={pagina}",
        "templated": true
    },
    "next": {
        "href": "/v3/consultas/franco@superautos.com?desde=2021-09-23&hasta=2021-10-23&pagina=2"
    }
}
La rel self, esta vez, es distinta de la URL que usaste ya que se aplicaron valores de default.
La rel next te brinda la URL exacta para buscar la siguiente página con los mismos parametros que usaste para encontrar la primera.
La rel search le dice a tu código como construir una URL con parámetros distintos ("construir" y por eso es templated).

¿Como "se digieren" los _links?

Dijimos que es nuestra intención no cambiar ni los models (JSONs) de entrada y salida ni los nombres de las rel.
Las rel que no son templated son propiedades como cualquier otra así que puedes usar directamente su href.
Para las rel con templated=true puedes construirte una función/metodo que reciba el href y un objeto con los valores a sustituir y, usando regex, reemplazar los valores de la URL devolviendo la URL completada. Algo quick and dirty, en JS, podría lucir así: 

function completeUrl(template, data) {
    const rxNames = /{(?<propname>\w+)}/gm;
    var propsnames = Array.from(new Set(Array.from(template.matchAll(rxNames)).map(e => e.groups.propname)).keys()),
        propsrx = propsnames.map(n => new RegExp('{' + n + '}', 'gm')),
        url = template;
    for (var i = 0; i < propsnames.length; i++) {
        url = url.replace(propsrx[i], data[propsnames[i]] || '');
    }
    return url;
}
Probalo con algo así 
completeUrl(entity._links.search.href, { operador: 'mario@superautos.com' })
Como notarás todo se termina transformando en manejar serializaciones/deserializaciones de objetos; lo haces para enviarnos un JSON en un POST, lo haces para interpretar el resultado de un GET y también lo puedes hacer para mandarnos parámetros del query-string. Las URLs templated no son nada más que objetos serializados de otra forma.

Ya no te queda otra...

Hasta acá llegamos con la inducción, ahora, si ya recibiste AppKey y AppSecret, no te queda otra que empezar con la autenticación.
No te olvides que si necesitas ayudas estamos en developers@autocosmos.com y siempre estaremos para compartir una cervecita aunque sea en video-call.

P.D. por favor no te olvides que developers@autocosmos.com es solo para gente que sepa que es un HTTP-request.