La v2 rompe compatibilidad con 7 cambios criticos (endpoints eliminados, URL de servidor cambiada, schema renombrado) y su scorecard global es F (44.66/100). El equipo debe corregir los breaking changes, estandarizar la convencion de nombres y completar la documentacion antes de publicar.
| Severidad | Categoria | Problema detectado | Ruta / Contexto |
|---|---|---|---|
| ERROR | parameters |
Parametro de ruta
contact_id no tiene required: true💡 Los path parameters deben ser siempre requeridos
|
GET /contacts/{contact_id} |
| WARN | naming |
Segmento de URL con verbo:
getContacts (anti-patron REST)💡 Usar sustantivos:
/contacts con metodo GET |
GET /getContacts |
| WARN | naming |
Segmento de URL con verbo:
createNote (anti-patron REST)💡 Preferir
/contacts/{id}/notes con POST |
POST /contacts/{contactId}/createNote |
| WARN | naming |
Segmento de URL con verbo:
updateStage (anti-patron REST)💡 Preferir PATCH /deals/{id} con body
{stage: ...} |
POST /deals/{dealId}/updateStage |
| WARN | naming |
Schema
contact_input deberia usar PascalCase💡 Renombrar a
ContactInput |
/components/schemas/contact_input |
| WARN | naming |
Query params
page_number, page_size usan snake_case💡 Usar camelCase:
pageNumber, pageSize |
GET /getContacts |
| WARN | naming |
Path parameter
contact_id usa snake_case en lugar de camelCase💡 Usar
contactId (consistente con el resto de la API) |
/contacts/{contact_id} |
| WARN | responses |
4 endpoints sin respuestas de error definidas (4xx/5xx)
💡 Anadir 400, 401, 404, 500 como minimo en cada operacion
|
GET /getContacts, PATCH /contacts, GET /deals, POST /deals, POST /updateStage |
| WARN | documentation |
Faltan campos
description y contact en info💡 Documentar la API con descripcion y contacto del equipo
|
/info |
/getContacts a /contacts (verbo en URL), /createNote a /notes, /updateStage a PATCH /deals/{id}.securitySchemes (bearerAuth) y aplicar security: [bearerAuth: []] en todos los endpoints. Sin esto la API carece de esquema de autenticacion documentado.ContactInput), camelCase para params (contactId, pageNumber), kebab-case para segmentos de ruta.description a cada operacion y al objeto info. El scorecard de documentacion es 37.9/100 — el mas critico tras performance (14/100).