So versionieren Sie Ihre Web-API

Sie sollten Ihre Web-API immer versionieren und gleichzeitig so viel URI wie möglich beibehalten. Stellen Sie sich eine Situation vor, in der Sie eine Web-API haben, die in der Produktion läuft und von Benutzern verwendet wird. Angenommen, Sie benötigen mehr Funktionen in der Web-API, müssen jedoch die vorhandenen Funktionen beibehalten. Möglicherweise haben Sie einige Benutzer, die die alte API noch benötigen, während andere eine Version mit neuen oder erweiterten Funktionen benötigen. Genau hier setzt die Web-API-Versionierung an.

Sie können Ihre Web-API auf eine der folgenden Arten versionieren:

  1. URLs verwenden: Versionsinformationen werden in der URL als Abfragezeichenfolge angegeben.
  2. Benutzerdefinierte Anforderungsheader verwenden: Die Versionsinformationen für Ihren Controller werden im Anforderungsheader angegeben, ohne dass Änderungen an der URL erforderlich sind.
  3. Accept-Header verwenden: Accept-Header definieren im Allgemeinen den Medientyp und die Zeichenkodierungen. Sie können Versionsinformationen für Ihre Web-API über Accept-Header übergeben, ohne die URL ändern zu müssen.

Versionierung der Web-API mithilfe von URLs

Betrachten Sie die folgenden Web - API - Controller, die genannt worden sind  AuthorsV1Controllerund AuthorsV2Controllerjeweils.

öffentliche Klasse AuthorsV1Controller: ApiController

    {

        [HttpGet]

        public IEnumerable GetAuthors ()

        {

          neuen String zurückgeben [] {"Joydip Kanjilal", "Gerben Wierda"};

        }}

    }}

öffentliche Klasse AuthorsV2Controller: ApiController

    {

        [HttpGet]

        public IEnumerable GetAuthors ()

        {

            neuen String zurückgeben [] {"Joydip Kanjilal, INDIA", "Gerben Wierda, Netherlands"};

        }}

    }}

Um diese Abbildung zu vereinfachen, habe ich GetAuthors()in jeden Controller eine Methode mit dem Namen integriert . Während GetAuthors()in AuthorsV1Controllerin nur die Autorennamen zurückgibt, gibt GetAuthors()in AuthorsV2Controller(die neue Version) die Autorennamen zusammen mit den Namen der Länder zurück, in denen die Autoren wohnen.

Das folgende Codeausschnitt zeigt, wie die beiden Controller die Register-Methode der WebApiConfigKlasse verwenden.

config.Routes.MapHttpRoute (

                Name: "WebAPIV1",

                routeTemplate: "api / v1 / {controller} / {id}",

                Standardeinstellungen: new {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}

            );

config.Routes.MapHttpRoute (

                Name: "WebAPIV2",

                routeTemplate: "api / v2 / {controller} / {id}",

                Standardeinstellungen: new {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}

            );

Sie können jetzt die Web-API-Methode GetAuthorsunter der folgenden URL aufrufen .

// localhost / WebAPI / api / v1 / Authors / GetAuthors

Versionierung der Web-API mithilfe des Anforderungsheaders

Sie können die Web-API-Versionierung auch mithilfe des Anforderungsheaders implementieren. Um dies zu erreichen, müssen Sie eine benutzerdefinierte Klasse implementieren, die die DefaultHttpControllerSelectorKlasse erweitert, und dann SelectControllerin Ihrer benutzerdefinierten Klasse überschreiben . Beachten Sie, dass die DefaultHttpControllerSelectorKlasse die IHttpControllerSelectorSchnittstelle implementiert . SelectControllerruft GetControllerNameintern auf und akzeptiert eine Instanz von HttpRequestMessageals Parameter.

Das folgende Codeausschnitt zeigt, wie Sie Versionsinformationen aus dem Anforderungsheader abrufen können.

private Zeichenfolge GetControllerVersionFromRequestHeader (HttpRequestMessage-Anforderung)

        {

            var acceptHeader = request.Headers.Accept;

            const string headerName = "Version";

            string controllerVersion = string.Empty;

            if (request.Headers.Contains (headerName))

            {

                controllerVersion = "V" + request.Headers.GetValues ​​(headerName) .First ();               

            }}

            return controllerVersion;

        }}

Versionierung der Web-API mithilfe des Accept-Headers

Die folgende Methode zeigt, wie Sie Versionsinformationen für Ihre Web-API aus dem Accept-Header abrufen können. Die Methode überprüft den MIME-Typ und gibt die Versionsinformationen entsprechend zurück. Wenn der Medientyp nicht ist application/json, wird die Standardversion als zurückgegeben V1.

private string GetControllerVersionFromAcceptHeader(HttpRequestMessage request)

        {

            var acceptHeader = request.Headers.Accept;

            string controllerVersion = string.Empty;

            foreach (var mime in acceptHeader)

            {

                if (mime.MediaType.Equals("application/json"))

                {

                    NameValueHeaderValue version = mime.Parameters.FirstOrDefault(v => v.Name.Equals("Version", StringComparison.OrdinalIgnoreCase));

                    controllerVersion = "V" + version.Value.ToString();

                    return controllerVersion;

                }

            }

            return "V1";

        }

You can invoke your Web API from Fiddler by passing the accept header as shown below.

Accept: application/json; charset=utf-8;version=2

The following code listing illustrates how you can override SelectController to select a controller dynamically. Note how GetControllerVersionFromRequestHeader has been used. If you would like to retrieve the controller version from the accept header, you should leverage GetControllerVersionFromAcceptHeader instead.

public override HttpControllerDescriptor SelectController(HttpRequestMessage request)

        {

            try

            {

                string controllerName = base.GetControllerName(request);

                var controllers = GetControllerMapping();

                var routeData = request.GetRouteData();

                string controllerVersion = GetControllerVersionFromRequestHeader(request);             

                controllerName = String.Format("{0}{1}", controllerName, controllerVersion);

                HttpControllerDescriptor controllerDescriptor;

                if (!controllers.TryGetValue(controllerName, out controllerDescriptor))

                {

                    string message = "No HTTP resource was found that matches the specified request URI {0}";

                    throw new HttpResponseException(request.CreateErrorResponse(System.Net.HttpStatusCode.NotFound, String.Format(message, request.RequestUri)));

                }

                return controllerDescriptor;

            }

            catch (Exception ex)

            {

                throw new HttpResponseException(request.CreateErrorResponse(System.Net.HttpStatusCode.NotFound, String.Format(ex.Message, request.RequestUri)));

            }

        }

You should add the following line in the Register method of the WebApiConfig class to provide support for controller selection at runtime.

config.Services.Replace (typeof (IHttpControllerSelector), neuer ControllerSelector ((config)));

Sie können jetzt Fiddler zum Testen Ihrer Web-API verwenden. Verwenden Sie die Registerkarte Composer von Fiddler und geben Sie die entsprechenden URL- und Versionsinformationen an. Wenn Sie möchten, dass Version 2 Ihres Web-API-Controllers aufgerufen wird, sollten Sie Version: 2beim Erstellen der Anforderungsheaderinformationen auf der Registerkarte Composer in Fiddler angeben .