API
Qué es una petición API
Una petición API es un programa pidiendo datos a otro, o pidiéndole que haga algo. La pregunta es el request. Lo que vuelve es la response. Esta página pide a Wikidata centros de datos y deja ambos intercambios donde puedes leerlos. El laboratorio de llamadas edita un script que hace este tipo de petición.
Entender el laboratorioCómo usarlo y por qué querrías hacerlo
Por qué querrías hacerlo
País, ciudad y nombre filtran una consulta de Wikidata de centros de datos, y la petición se sienta junto a las filas. Esta página no llama a Adobe.
Cómo usarlo
- Escribe un país, una ciudad o un nombre. Los filtros se quedan en texto plano.
- La página arma un select de SPARQL con esos tres.
- La llamada va a query.wikidata.org.
- Una respuesta guardada se puede reutilizar en vez de llamar otra vez.
Ida y vuelta
Una petición y luego una respuesta
Un cliente construye una petición. Nombra un método, una URL y unas pocas cabeceras. A veces añade un cuerpo. Un servidor lo lee y envía una respuesta: un código de estado, cabeceras y a menudo un cuerpo. Entonces ese intercambio termina.
La demostración de más abajo es la ida y vuelta dos veces. Tu navegador llama a GET /api/data-centers en este sitio. Este sitio llama a Wikidata. Ambos intercambios se muestran con el estado, las cabeceras, el tiempo y el cuerpo.
1 · Cliente
El navegador, o el servidor de este sitio actuando por el navegador.
2 · Petición
Método, URL, cabeceras y un cuerpo cuando el método lo necesita.
3 · Respuesta
Estado, cabeceras y el cuerpo que renderizas o lees.
Métodos
El verbo dice qué quieres que se haga
Estos cuatro cubren la mayoría de las API. Esta demostración solo lee, así que cada llamada es un GET.
GET
Leer
Pide una copia. Una búsqueda es un GET. Enviarla otra vez debería dejar los datos del servidor como estaban.
POST
Enviar
Envía algo nuevo, o pide al servidor que haga un trabajo. El formulario de contacto de este sitio es un POST.
PUT
Sustituir
Pon una copia nueva en el lugar de lo que ya está almacenado en esa URL.
DELETE
Eliminar
Pide al servidor que borre el recurso de esa URL.
Estado
El código dice cómo fue
El primer dígito es la familia. 2 significa éxito, 3 significa mirar en otro sitio, 4 significa que la petición tiene un problema, 5 significa que el servidor falló.
200 OK
La petición funcionó. El cuerpo es la respuesta.
301 Movido
El recurso tiene una URL nueva. La cabecera Location la nombra. 302 es un traslado temporal.
400 Petición incorrecta
El servidor no pudo entender la petición. Un campo de búsqueda con un carácter que esta página rechaza recibe un 400.
401 No autorizado
La petición necesita credenciales. El servidor no sabe quién llama.
403 Prohibido
El servidor entendió la petición y la rechaza.
404 No encontrado
Esa URL no apunta a un recurso.
429 Demasiadas peticiones
Quien llama va demasiado rápido. Esta página se frena para que un montón de búsquedas comparta unas pocas llamadas.
500 Error del servidor
El servidor falló de su lado. 502 y 504 significan que un servidor intermedio, o este sitio, no obtuvo una respuesta utilizable.
Cabeceras
Notas al margen
Las cabeceras son líneas de metadatos alrededor del cuerpo. Una petición puede enviar Accept: application/json para nombrar un formato que puede leer, y User-Agent para decir quién llama. Una respuesta puede enviar Content-Type para nombrar el formato del cuerpo, y Cache-Control para decir cuánto tiempo se puede guardar una copia.
Este sitio envía un User-Agent que nombra el sitio y esta página. Wikidata pide a quien llama que lo haga. La clave, si una API la necesitara, también sería una cabecera, y se quedaría en el servidor.
Cadena de consulta
Los parámetros estrechan un GET
La parte de una URL después de ? es un conjunto de claves y valores. country, city y name son opcionales en /api/data-centers. Dejarlos en blanco devuelve los centros de datos más recientes. Rellenar cualquiera estrecha los resultados. /api/data-centers?country=US&city=Dallas&name=DataBank envía los tres.
Esta página pone tu búsqueda en esa ruta. El servidor la convierte en una consulta de Wikidata y coloca el texto en el parámetro query de Wikidata. Esa URL es larga. El panel muestra la real.
Autenticación
Quién puede preguntar
Ninguna
Cualquiera puede leer. El servicio de consulta de Wikidata funciona así para una búsqueda como la de abajo. No hay una clave que copiar ni una cuenta en la que iniciar sesión.
Clave de API
Una cadena secreta, normalmente en una cabecera como Authorization. El servidor comprueba la cadena y luego hace el trabajo. Una página debería guardar la clave en el servidor. El navegador no necesita verla.
OAuth
Un apretón de manos breve. Apruebas una app y la app recibe un token que caduca. Las peticiones posteriores llevan el token. Puedes revocarlo sin cambiar tu contraseña.
Cuerpo
Los formatos que habla una API
La cabecera Content-Type nombra cuál de estos es el cuerpo. La demostración pide JSON e imprime el cuerpo que recibe.
JSON
application/json
Texto hecho de objetos y listas. Wikidata lo devuelve cuando la petición lo pide. El panel de abajo es ese cuerpo.
XML
application/xml
Texto hecho de etiquetas. Muchas API antiguas todavía responden en XML. Los mismos hechos, otra grafía.
CSV
text/csv
Filas de valores separados por comas. Una descarga de hoja de cálculo suele ser CSV. Fácil de recorrer, incómodo para hechos anidados.
Datos de formulario
application/x-www-form-urlencoded
Cómo envía un navegador un formulario. Un tipo parece una cadena de consulta en el cuerpo. multipart/form-data puede llevar un archivo.
Formas
REST, GraphQL y webhooks
REST
Muchas URL, un recurso en cada una. El método HTTP dice qué hacer. Una instalación podría vivir en /facilities/1234. GET la lee. DELETE la elimina.
GraphQL
Normalmente una URL. El cuerpo de la petición nombra los campos que quiere el cliente, y la respuesta tiene la forma de esa petición. El cliente pide un nombre y una ciudad, y se salta el resto.
Webhooks
La otra dirección. Le das a un servicio tu URL y te hace POST cuando pasa algo, así que no tienes que seguir preguntando. El laboratorio de webhooks firma esa entrega y guarda un registro.
El servicio de consulta de Wikidata es una URL que ejecuta una consulta, más cerca de esa idea de un solo endpoint que de un diseño de un recurso por URL. El sobre sigue siendo HTTP normal, que es lo que mide el panel.
Laboratorio de recolección vigila las peticiones de este navegador. Esta página vigila una petición que este servidor hace por ti.
RecorridoCómo lo hicimosMostrarOcultar
El ajuste de proveedor de ejemplo está marcado abajo. Los números de eVar y de event son ejemplos. Este laboratorio no llama a Adobe.
El laboratorio de API lee país, ciudad y nombre, pide centros de datos a Wikidata y muestra la petición junto a las filas. El laboratorio no llama a Adobe.
Dejar los tres filtros en texto plano
readFilters recorta country, city y name. Un valor demasiado largo o con caracteres fuera del conjunto permitido se rechaza antes de cualquier llamada aguas arriba.
Armar un select de SPARQL
dataCenterQuery selecciona ítems que son centros de datos, con etiquetas en inglés, país, lugar, operador, fecha de apertura, coordenada y hora de modificación. Los filtros se añaden, y la consulta ordena por la hora de modificación.
Llamar a query.wikidata.org
callWikidata hace GET de esa URL con una cabecera accept de JSON de SPARQL y un tiempo límite de 12 segundos. Un host final distinto de query.wikidata.org se rechaza. facilitiesFromSparql agrupa los bindings por id de ítem.
Reutilizar una respuesta guardada
loadDataCenters devuelve la copia en memoria cuando los mismos filtros se pidieron dentro de la ventana de caché. La ruta añade la atribución y una cabecera Server-Timing. Esta página no llama a trackLabEvent.
Del código
El select. Los filtros y el límite se añaden después de este bloque.
export function dataCenterQuery(filters: SearchFilters) {
return `SELECT ?item ?itemLabel ?countryLabel ?iso ?adminLabel ?operatorLabel ?inception ?modified ?coord WHERE {
?item wdt:P31 wd:Q671224 .
OPTIONAL { ?item rdfs:label ?itemLabel . FILTER(LANG(?itemLabel) = "en") }
OPTIONAL {
?item wdt:P17 ?country .
OPTIONAL { ?country rdfs:label ?countryLabel . FILTER(LANG(?countryLabel) = "en") }
OPTIONAL { ?country wdt:P297 ?iso . }
}
OPTIONAL {
?item wdt:P131 ?admin .
OPTIONAL { ?admin rdfs:label ?adminLabel . FILTER(LANG(?adminLabel) = "en") }
}
OPTIONAL {
?item wdt:P137 ?operator .
OPTIONAL { ?operator rdfs:label ?operatorLabel . FILTER(LANG(?operatorLabel) = "en") }
}
OPTIONAL { ?item wdt:P571 ?inception . }El GET aguas arriba. La comprobación del host sigue a la respuesta.
async function callWikidata(filters: SearchFilters): Promise<LoadResult> {
const url = dataCenterRequestUrl(filters)
const started = performance.now()
let response: Response
try {
response = await fetch(url, {
method: "GET",
headers: {
Accept: REQUEST_HEADERS[0].value,
"User-Agent": REQUEST_HEADERS[1].value,
},
cache: "no-store",
redirect: "follow",
signal: AbortSignal.timeout(12_000),
})Google y Adobe
Este laboratorio no encola un evento propio. El bloque de Google muestra un ejemplo de cómo rastrearías la interacción. Adobe también es un ejemplo.
Este laboratorio no encola un evento de analítica propio. Después de Aceptar, el sitio sigue encolando virtual_page_view de la página, con page_path y page_title. Los clics dentro de una región data-track-ignore no se registran. El push de abajo es un ejemplo, no una llamada de esta página. Este sitio no llama a gtag('set') ni a Adobe.
Solo ejemplo. Esta página no hace push de este objeto.
// Example only. This lab does not queue this event.
dataLayer.push({
event: "data_center_search_example",
country: "US",
row_count: 0,
})Implementación de ejemplo. Este sitio no llama a Adobe. eVar47, prop47 y event47 son números de variable de ejemplo. En Launch, un elemento de datos lee el valor y una regla lo envía cuando el valor cambia. En el report suite, habilita eVar47 con asignación Most Recent y haz que expire en el hit. Una processing rule no hace falta si el elemento de datos se mapea directo a esa eVar.
Payload de alloy de ejemplo. _example es un esquema de relleno, no un inquilino real.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
searchCountry: "US",
},
},
})Hit de ejemplo. eVar47 tiene alcance de hit en este ejemplo. prop47 muere en el mismo hit.
s.eVar47 = "US"
s.prop47 = "US"
s.events = "event47"
s.linkTrackVars = "eVar47,prop47,events"
s.linkTrackEvents = "event47"
s.tl(true, "o", "data_center_search_example")Traducción
Cada campo del laboratorio, el nombre en GA4 y la variable de Adobe de ejemplo. El alcance es la parte que suele perderse en la traducción.
Filtro de país
GA4. No se envía. country es un parámetro de consulta en /api/data-centers.
Adobe. eVar47 de ejemplo, expira en el hit.
Alcance. Hit. Un país con alcance de usuario mantendría esta búsqueda en la visita siguiente.
Ciudad y nombre
GA4. No se envía. Acotan la misma consulta SPARQL.
Adobe. prop47 de ejemplo en el hit.
Alcance. Hit. Son campos de búsqueda, no propiedades de la visita.
Conteo de filas
GA4. No se envía. rowCount es el número de instalaciones en la respuesta.
Adobe. Ejemplo: no escribas el conteo en eVar47.
Alcance. Un campo de la respuesta. No es una métrica de evento.
Caché aguas arriba
GA4. No se envía. La cabecera de respuesta X-Upstream-Cache dice hit, miss, stale o none.
Adobe. prop47 de ejemplo si enviaras esa palabra de caché. No se envía.
Alcance. Una propiedad de esta respuesta, no del usuario.
Recomendado a continuación
Por qué estas propuestasLeyendo las transiciones de recorrido…