Utveckla ditt API med versionskontroll

Artikel
05/09/2023

Anpassade anslutningsprogram för Azure Logic Apps, Microsoft Power Automate eller Microsoft Power Apps måste tillhandahålla en OpenAPI-specifikationsfil. Denna OpenAPI-specifikation definierar enskilda startpunkter som kallas åtgärder. Varje åtgärd har ett unikt operationId och en unik kombination av urlPath och HttpVerb.

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

Dessa åtgärder kan växa och ändras med tiden när funktioner läggs till eller utvidgas. Vissa ändringar är bara tillägg och bryter inte nödvändigtvis det kontrakt som finns mellan klienter och servrar. Att lägga till nya parametrar, returnera mer data eller tillåta mer flexibla indata kan ingå i den här kategorin.

Många ändringar kan dock faktiskt bryta kontraktet som beskrivs i OpenAPI-specifikationen. Att ta bort parametrar, inte längre stödja vissa indata eller ändra innebörden och beteendet för indata, utdata eller själva åtgärden, faller under kategorin ”icke-bakåtkompatibel ändring”.

För att kunna utveckla ett API på ett säkert sätt är det viktigt att följa ett mönster som kan navigeras av klienter. Det är API:ets ansvar att upprätthålla bakåtkompatibilitet, kommunicera avsikten och definiera attribut för versionshantering. Det är klientens ansvar att antingen visa eller dölja åtgärder som är föråldrade, förfallna eller som kan ha nya versioner tillgängliga. På så sätt kan driften utvidgas och utvecklas över tid utan att orsaka onödig sårbarhet i program som är beroende av dem.

API-anteckning

OpenAPI har inte inbyggt stöd för åtgärdsversionshantering. För att uppnå vårt mål görs mycket av arbetet genom objektet x-ms-api-annotation, som tillämpas både i det globala omfånget och i åtgärdsomfånget. Det globala objektet innehåller egenskaper som gäller för API:et som helhet:

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}

Egenskap	Värden	Standard	Beskrivning
status	`"Preview"` `"Production"`	`"Preview"`	Status för API:et som en helhet—från förhandsversion till produktion som användnings- och stabilitetsstyrning

I det operativa omfånget innehåller det här objektet mer detaljerade egenskaper. Det finns också ytterligare egenskaper utanför objektet som tillämpas och deltar i processen för utveckling av versioner:

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}

Egenskap	Värden	Standardvärde	Beskrivning
inaktuell	`null` `false` `true`	`false`	Anger om åtgärden är föråldrad
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	Avsedd synlighet och tydlighet för den här åtgärden, där `null` eller `""` innebär ett normalt tillstånd
status	`"Preview"` `"Production"`	`"Production"`	Status för åtgärden—detta kan skilja sig från tillståndet för själva API:et, men om det inte anges ärvs det från API-statusen på den högsta nivån
familj	{gemensamt åtgärdsnamn}	operationName	Namn som tillämpas för varje revidering av den här åtgärden
revision	numerisk (1,2,3...)	`1`	Revidering av den angivna åtgärdsfamiljen
förfaller	ISO8601-datum	(inget)	Valfritt tips för klienten som anger planerat slut på stödet

Inaktuell kan anges som true när det inte längre är önskvärt att klienter använder den här åtgärden. Den här egenskapen finns i specifikationen OpenAPI Fixed Fields.

Synlighet är en indikator för åtgärdens avsedda relativa tydlighet. En synlighet som anges som "Important" visar att åtgärden ska finnas högt upp i listan och visas på ett framträdande sätt. En normal synlighet (som anges av null eller en tom sträng "") är standard och innebär att åtgärden visas i listan, förmodligen efter de viktiga åtgärderna. En synlighet som anges som "Advanced" visar att åtgärden kan ligga längre ned i listan eller till och med dold bakom en expansionskontroll. Avancerade åtgärder kan vara svårare att använda, mindre populära eller mindre användbara. En synlighet som anges som "Internal" visar att åtgärden inte ska visas för användare och endast ska användas internt. Interna åtgärder är programmässigt användbara och värdefulla, men är inte avsedda för slutanvändare. Interna åtgärder kan också markeras som sådana för att dölja dem från användargränssnitt under föråldrandeprocessen, utan att de faktiskt tas bort från API:et, vilket annars skulle orsaka en icke-bakåtkompatibel ändring.

Status anger stabiliteten för API:et eller åtgärden. "Preview" anger att åtgärden eller API:et är nytt och potentiellt oprövat. Förhandsversion är en indikator om att man för produktionssystem ska iaktta försiktighet i fråga om beroenden. När åtgärder eller API:er är mer etablerade och det är beprövat att de uppfyller tillförlitlighetskrav, lyckade resultat och skalbarhet, kan de uppgraderas till statusen "Production".

Följande krav gäller normalt åtgärder som kan få statusen "Production":

80 % slutförandefrekvens under en period på tre veckor
- definierat som procent av HTTP-svarskoder i 2xx-intervallet
99,9 % varaktig pålitlighet under en period på tre veckor
- definierat som procent av HTTP-svarskoder i icke-5xx-intervallet (502, 504 och 520 ingår inte i den här beräkningen)

Familj anger relationen mellan åtgärder som konceptuellt sett är samma åtgärd, men som utgör olika revisioner med potentiellt icke-bakåtkompatibla ändringar. Flera åtgärder delar samma familjenamn om de anses vara revisioner av varandra och sekvenseras av sina unika revisionsnummer.

Revision anger utvecklingsordningen för åtgärden inom åtgärdsfamiljen. Varje åtgärd inom en familj har en revidering som är ett heltalsindex som anger sekvens. En tom revision betraktas som revision 1. När nyare revisioner av en åtgärd är tillgängliga bör klienterna visa dem mer framträdande och rekommendera dem mer avsiktligt, men ändå tillåta att du väljer potentiellt äldre revisioner som ännu inte är inaktuella.

Upphör är valfritt och anger en potentiell tidsgräns för livslängden då stöd för åtgärden inte längre garanteras. Detta bör endast anges för föråldrade åtgärder och visas för närvarande inte i något gränssnitt.

Åtgärders livslängd

Åtgärder har en förutsägbar livslängd vilket kan visas i exempel.

Startpunkt

Inledningsvis kanske åtgärder inte nödvändigtvis anger något om revisioner. De här åtgärderna har tillämpade standardvärden och betraktas därför som revision 1 i ett familjenamn som motsvarar operationId.

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

Detta motsvarar definitionen mer explicit:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

Åtgärdsinitiering

De flesta utvecklingar av ett API utgör tillägg av en åtgärd. Det kan exempelvis vara nya metoder och nya revisioner av befintliga metoder. För att på ett säkert sätt initiera en ny revision justerar du OpenAPI-specifikationen på det här sättet:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Viktigt

Observera att GetItems v2 har ett unikt operationId och visas initialt i förhandsversionsstatus. Observera också att GetItems v1 nu har avancerad synlighet, så att det inte visas på ett framträdande sätt.

Föråldrade åtgärder

Ibland kan befintliga v1-startpunkter finnas kvar för alltid, om de fortsätter att tillföra värde och det inte finns någon egentlig anledning att avsluta dem. Många v2-startpunkter ersätter dock avsiktligt v1-startpunkten. För att på ett säkert sätt göra detta bör all trafik uppnå en nominell nollpunkt för den ursprungliga åtgärden. När telemetri bekräftar dessa omständigheter kan följande ändring göras:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Viktigt

Observera att GetItems v1 nu är markerat som föråldrat. Det här är den sista övergångsfasen för föråldrade åtgärder. GetItems v2 har nu fullständigt ersatt GetItems v1.

Varför ska jag bry mig om det?

Det finns många skäl att beakta versionshantering för åtgärder. I första hand ser du till att klienter som Azure Logic Apps och Power Automate fortsätter att fungera korrekt när användare integrerar åtgärder för kopplingar i sina dataflöden. Åtgärder ska följa versionshanteringen enligt metoden ovan när:

En ny revision av en åtgärd läggs till
En befintlig åtgärd lägger till eller tar bort parametrar
En befintlig åtgärd ändrar indata eller utdata betydligt

Strikt bedömning

Det kan finnas fall där du kan klara dig utan versionshantering—men du bör vara försiktig när du gör det, och utföra många tester för att se till att du inte har förbisett specifika fall där användare oväntat kan ha blivit bortkopplade. Här är några situationer då du kan klara dig utan den:

En ny åtgärd läggs till.

Detta skulle inte specifikt koppla bort befintliga klienter.
En ny valfri parameter läggs till i en befintlig åtgärd.

Detta skulle inte bryta befintliga anrop, men måste övervägas noggrant.
Beteendet ändras en aning för en befintlig åtgärd.

Detta kanske inte avbryter befintliga anropare, baserat på själva ändringen och vad användarna förlitar sig på. Detta är det mest osäkra fallet, eftersom en betydande skillnad i godkännandet av indata, generering av utdata, tidsinställning eller bearbetning kan påverka beteendet för åtgärden på sätt som kan göra det svårt att fastställa risken för ändringen.

Vi rekommenderar alltid att vara försiktig och att du upprepar en revidering när du gör en icke-trivial API-ändring.

Ge feedback

Vi uppskattar feedback på problem med vår plattform för anslutningsprogram eller förslag på nya funktioner. Om du vill lämna feedback går du till Skicka problem eller få hjälp med anslutningsprogram och väljer typ av feedback.