CUBS har valgt at udfase dette API i forbindelse med almindelig vedligeholde af vores API’er.
API-endpointet /api/agreements/v4/customer-agreements udfases, da det kombinerer forskellige typer af indhold i én respons, hvilket ikke følger best practice for REST APIs. Desuden mather API’et ikke aktuelle vores retningslinier for navngivning af URL’er og overholder ikke best practice for REST API’er.
Hvorfor er de nye API’er bedre?
Det gamle API returnerede en sammenblanding af aftaler, leverancer, installationsadresser og betalingsmetoder i én respons. Dette bryder med REST-principper på flere måder:
- Single Responsibility - Hvert endpoint bør håndtere én ressourcetype. Det gamle API blandede flere forskellige ressourcer sammen.
- Ressource-baserede URI’er - REST-endpoints skal repræsentere specifikke ressourcer. De nye API’er har klare, ressource-baserede stier som
/agreements/og/deliveries/. - Bedre caching - Når data er adskilt, kan hver ressourcetype caches uafhængigt, hvilket forbedrer performance.
- Fleksibilitet - Du kan nu hente præcis den information du har brug for, uden at skulle hente et stort kombineret datasæt.
- Skalerbarhed - Adskilte endpoints kan skaleres og optimeres individuelt baseret på deres specifikke behov.
Alternative API’er
Funktionaliteten erstattes af følgende specialiserede endpoints:
POST /api/core/customers/v2/{customerExternalId}/agreements- Hent alle aftaler for en kundeGET /api/core/customers/v2/{customerExternalId}/payment-subscriptions- Hent kundens betalingsabonnementerGET /api/core/agreements/v1/{agreement_external_id}- Hent detaljer om en specifik aftaleGET /api/core/agreements/v5/{agreement_external_id}/deliveries- Hent leverancer under en aftaleGET /api/core/deliveries/v2/{delivery_type}/{delivery_external_id}- Hent detaljer om en specifik leverance inkl. installationsadresse
Mapping af data fra gammelt til nyt API
| Data fra gammelt API | Findes i nyt API |
|---|---|
| Aftaledetaljer (id, nummer, status, type, fakturering) | GET /api/core/agreements/v1/{agreement_external_id} |
| Kundens aftaler (liste) | POST /api/core/customers/v2/{customerExternalId}/agreements |
subscription_methods (betalingsmetoder) | GET /api/core/customers/v2/{customerExternalId}/payment-subscriptions |
address (installationsadresse) | GET /api/core/deliveries/v2/{delivery_type}/{delivery_external_id} |
| Leverancer under aftale | GET /api/core/agreements/v5/{agreement_external_id}/deliveries |
Bemærk: Du skal nu lave flere API-kald for at få samme data, men til gengæld får du kun præcis den data du har brug for, og kan cache hver ressourcetype individuelt.
Hvad skal du gøre?
Opdater dine integrationer til at anvende de nye endpoints. De nye API’er giver mere fleksibilitet og følger moderne REST-principper med adskillelse af forskellige ressourcetyper.
Se den komplette API-dokumentation på api.cubs.dk.