Consistencia de la API

Patrones consistentes en todos los endpoints de X API v2

X API v2 está diseñada con patrones consistentes en todos sus endpoints. Una vez que aprendas cómo funciona un endpoint, podrás aplicar los mismos patrones en el resto.

---

Patrones consistentes

Estructura de la URL

Todos los endpoints de la API v2 siguen un patrón predecible:

/version/resource/{id}?parameters
/version/resource/verb?parameters

Ejemplos:

/2/tweets/1234567890                    # Get a specific post
/2/tweets/search/recent                 # Search recent posts
/2/users/by/username/xdevelopers        # Obtener usuario por nombre de usuario
/2/users/1234/followers                 # Get user's followers

Estructura de la respuesta

Todas las respuestas usan la misma estructura principal:

{
  "data": { ... },       // Objeto(s) principal(es)
  "includes": { ... },   // Objetos expandidos
  "meta": { ... },       // Paginación, recuentos
  "errors": [ ... ]      // Errores parciales (si los hay)
}

Formato de ID

Todos los id se devuelven como cadenas de texto para garantizar la compatibilidad entre lenguajes:

{
  "id": "1234567890123456789",
  "author_id": "2244994945"
}

---

Campos y expansions

Los mismos parámetros de campos y expansions funcionan de manera coherente:

Objeto	Parámetro fields	Funciona en
Publicación	tweet.fields	Todos los endpoints que devuelven publicaciones
Usuario	user.fields	Todos los endpoints que devuelven usuarios
Media	media.fields	Todos los endpoints con expansions de medios
Encuesta	poll.fields	Todos los endpoints con expansions de encuestas
Lugar	place.fields	Todos los endpoints con expansions de lugares

---

Esquemas de objetos

El mismo tipo de objeto tiene los mismos campos independientemente del endpoint que lo devuelva:

• Una Publicación devuelta por search tiene los mismos campos que una Publicación devuelta por lookup
• Un usuario devuelto por followers tiene los mismos campos que un usuario devuelto por search
• Los objetos expandidos coinciden con sus homólogos independientes

---

Autenticación

Todos los endpoints utilizan los mismos métodos de autenticación:

Método	Formato de la cabecera
Bearer Token	Authorization: Bearer {token}
OAuth 1.0a	Authorization: OAuth {parameters}
OAuth 2.0	Authorization: Bearer {user_token}

---

Manejo de errores

Los errors tienen un formato coherente:

{
  "title": "Solicitud no válida",
  "detail": "Falta el parámetro de consulta",
  "type": "https://api.x.com/2/problems/invalid-request"
}

Ver todos los tipos de error →

---

Paginación

Todos los endpoints paginados usan el mismo sistema de tokens:

Parámetro	Descripción
max_results	Resultados por página
pagination_token	Token de next_token o previous_token

Más información sobre la paginación →

---

Convenciones de nomenclatura

• Ortografía del inglés estadounidense (favorites no favourites)
• Snake_case para nombres de campos (author_id, created_at)
• Terminología consistente (retweet_count, no repost_count en campos)

---

Valores vacíos

Los campos sin valor se omiten y no se devuelven como null:

// User without a bio
{
  "id": "1234",
  "name": "Example User",
  "username": "example"
  // "description" se omite, no es null
}

---

Consistencia de entidades

El objeto entities solo contiene entidades extraídas del texto:

• urls
• hashtags
• mentions
• cashtags

Los elementos multimedia y las encuestas están en attachments, no en entities.

---

Qué significa esto para ti

Aprende una vez, úsalo en todas partes

Los patrones que aprendas en un endpoint se aplican a todos los endpoints.

Respuestas predecibles

Los mismos tipos de objeto tienen la misma estructura en toda la API.

Código más simple

Crea funciones reutilizables para patrones comunes.

Depuración más sencilla

Los formatos de error coherentes simplifican la resolución de problemas.

---

Informar sobre inconsistencias

¿Has encontrado alguna inconsistencia? Háznoslo saber:

• Developer Forum
• Developer Feedback