Twenty fue creado para ser amigable con los desarrolladores, ofreciendo APIs potentes que se adaptan a tu modelo de datos personalizado. Proveemos cuatro tipos de API distintos para satisfacer diferentes necesidades de integración.
Enfoque centrado en el desarrollador
Twenty genera APIs específicamente para tu modelo de datos, lo que significa:
- No se requieren IDs largos: Usa los nombres de tus objetos y campos directamente en los endpoints.
- Objetos estándar y personalizados tratados por igual: Tus objetos personalizados reciben el mismo tratamiento de API que los incorporados.
- Endpoints dedicados: Cada objeto y campo recibe su propio endpoint de API.
- Documentación personalizada: Generada específicamente para el modelo de datos de tu espacio de trabajo.
Tu API personalizada genera documentación accesible mediante Configuración → API & Webhooks después de crear una clave de API. Esta documentación refleja tu modelo de datos exacto y las configuraciones de campo.
Los Cuatro Tipos de API
Twenty ofrece APIs en formatos REST y GraphQL:
APIs REST
- Propósito: Gestionar la estructura de tu espacio de trabajo y modelo de datos
- Casos de uso:
- Crear, modificar o eliminar objetos y campos
- Configurar ajustes del espacio de trabajo
- Gestionar relaciones del modelo de datos
- Acceso: Disponible a través de endpoints REST
2. API REST Core
- Propósito: Gestionar los registros de datos reales
- Casos de uso:
- Crear, leer, actualizar, borrar registros
- Consultar datos específicos
- Gestionar relaciones de registros
- Acceso: Disponible a través de endpoints REST
APIs GraphQL
- Propósito: Igual que la API REST de Metadatos pero con beneficios de GraphQL
- Casos de uso: Misma gestión de espacio de trabajo y modelo de datos
- Beneficios adicionales:
- Consultar múltiples tipos de metadatos en una solicitud
- Selección precisa de campos
- Mejor rendimiento para consultas complejas
4. API Core de GraphQL
- Propósito: Igual que la API REST Core pero con ventajas de GraphQL
- Casos de uso: Misma gestión de registros de datos
- Beneficios adicionales:
- Operaciones por lotes: Disponibles para todas las operaciones
- Operaciones de Upsert: Crear o actualizar registros en una llamada
- Consultas de relaciones en solicitudes únicas
- Extracción precisa de datos
Operaciones por Lotes
Soporte de Lotes REST y GraphQL
Tanto las APIs REST como GraphQL soportan operaciones por lotes para la mayoría de las acciones:
- Tamaño del lote: Hasta 60 registros por solicitud
- Operaciones disponibles: Crear, actualizar, eliminar múltiples registros
- Rendimiento: Significativamente más rápido que las llamadas individuales a API
Características Exclusivas de GraphQL
- Upsert por lotes: Solo disponible en APIs GraphQL
- Uso: Utiliza nombres de objetos plurales (por ejemplo,
CrearEmpresas en lugar de CrearEmpresa)
- Requisito: Es por esto que los nombres de objetos singulares y plurales deben ser distintos
Acceso a la Documentación de la API
- Ve a Configuración → API & Webhooks
- Crea una clave de API (requerida para el acceso a la documentación)
- Accede a tu documentación personalizada y área de pruebas
- Prueba las APIs con tu modelo de datos real
Tu documentación es única para tu espacio de trabajo porque refleja tus objetos personalizados, campos y relaciones.
Cuándo Usar Cada API
- Configurando tu modelo de datos
- Creando objetos o campos personalizados
- Configurando ajustes del espacio de trabajo
Usa las APIs Core cuando:
- Gestionando los datos del día a día (Personas, Empresas, Oportunidades)
- Integrándose con sistemas externos
- Construyendo aplicaciones personalizadas
- Automatizando flujos de trabajo de datos
Elige GraphQL cuando:
- Necesites operaciones por lotes
- Desees minimizar las llamadas a API
- Necesites funcionalidad de upsert
- Estés construyendo integraciones complejas
Elige REST cuando:
- Prefieras una estructura de API más sencilla
- Estés construyendo integraciones básicas
- Tu equipo esté más familiarizado con REST
- Necesites operaciones CRUD directas
Próximos Pasos
- Configuración de API & Webhooks: Aprende cómo crear claves de API y webhooks
- Documentación Personalizada: Accede a tus documentos API personalizados vía Configuración → API & Webhooks
