Návrh rozhraní APIAPI design

Většina moderních webových aplikací zveřejňují rozhraní API, který můžou klienti používat k interakci s aplikací.Most modern web applications expose APIs that clients can use to interact with the application. Dobře navrženou webového rozhraní API by měl zaměřte se na podporu:A well-designed web API should aim to support:

  • Nezávislost platformy.Platform independence. Jakýkoli klient byste měli mít k volání rozhraní API, bez ohledu na to, jak rozhraní API se implementuje interně.Any client should be able to call the API, regardless of how the API is implemented internally. To vyžaduje pomocí standardních protokolů která mají mechanismus, při němž klienta a můžete na formát dat pro výměnu shodnou webovou službu.This requires using standard protocols, and having a mechanism whereby the client and the web service can agree on the format of the data to exchange.

  • Služba vývoj.Service evolution. Webové rozhraní API by mohli momentální a přidejte funkce nezávisle z klientské aplikace.The web API should be able to evolve and add functionality independently from client applications. Protože rozhraní API zpracovaní existující klientské aplikace by měly být nadále fungovat bez úprav.As the API evolves, existing client applications should continue to function without modification. Všechny funkce musí být zjistitelný, takže ho můžete využít plně klientské aplikace.All functionality should be discoverable, so that client applications can fully utilize it.

Tento návod popisuje problémy, které byste měli zvážit při návrhu webového rozhraní API.This guidance describes issues that you should consider when designing a web API.

Úvod do RESTIntroduction to REST

V roce 2000 Royi Fielding navrhované přenosu REST (Representational State) jako architektury přístup k navrhování webové služby.In 2000, Roy Fielding proposed Representational State Transfer (REST) as an architectural approach to designing web services. REST je architektury styl pro vytváření distribuované systémy založené na hypermédií.REST is an architectural style for building distributed systems based on hypermedia. REST je nezávislý na libovolný protokol pro základní a se nevztahuje na HTTP.REST is independent of any underlying protocol and is not necessarily tied to HTTP. Však většiny běžných implementací REST používat protokol HTTP jako protokol pro aplikace a tato příručka se zaměřuje na návrh rozhraní REST API pro protokol HTTP.However, most common REST implementations use HTTP as the application protocol, and this guide focuses on designing REST APIs for HTTP.

Primární výhod REST prostřednictvím protokolu HTTP je, že používá otevřených standardů a nemá vazbu implementace rozhraní API nebo klientské aplikace žádné konkrétní implementace.A primary advantage of REST over HTTP is that it uses open standards, and does not bind the implementation of the API or the client applications any specific implementation. Například webové služby REST může být napsané v ASP.NET a klientské aplikace můžete používat libovolný jazyk nebo sada nástrojů, která může generovat požadavků HTTP a analyzovat odpovědi HTTP.For example, a REST web service could be written in ASP.NET, and client applications can use any language or toolset that can generate HTTP requests and parse HTTP responses.

Tady jsou některé z hlavní zásady rozhraní RESTful API pomocí protokolu HTTP:Here are some of the main design principles of RESTful APIs using HTTP:

  • Rozhraní REST API jsou uspořádaná kolem prostředky, které jsou jakýkoli druh objektu, dat nebo služba, která je přístupná klientem.REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client.

  • Prostředek má identifikátor, což je identifikátor URI, který jednoznačně identifikuje tento prostředek.A resource has an identifier, which is a URI that uniquely identifies that resource. Například může být identifikátor URI pro konkrétního zákazníka pořadí:For example, the URI for a particular customer order might be:

    http://adventure-works.com/orders/1
    
  • Interakce klientů s služby nahrazením reprezentace prostředků.Clients interact with a service by exchanging representations of resources. Mnoho webových rozhraní API pomocí JSON jako formát exchange.Many web APIs use JSON as the exchange format. Například požadavek GET na identifikátor URI uvedené výše může vrátit tento text odpovědi:For example, a GET request to the URI listed above might return this response body:

    {"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}
    
  • Rozhraní REST API použijte jednotné rozhraní, která pomáhá oddělit implementace klienta a služby.REST APIs use a uniform interface, which helps to decouple the client and service implementations. Pro rozhraní REST API založený na protokolu HTTP, jednotné rozhraní obsahuje pomocí protokolu HTTP standardní příkazy provedení operací s prostředky.For REST APIs built on HTTP, the uniform interface includes using standard HTTP verbs perform operations on resources. Nejběžnější operace jsou GET, POST, PUT, PATCH a DELETE.The most common operations are GET, POST, PUT, PATCH, and DELETE.

  • Rozhraní REST API používají model bezstavové požadavku.REST APIs use a stateless request model. Požadavky HTTP měly být nezávislé a může dojít v libovolném pořadí, takže udržuje informace o přechodný stav mezi požadavky není vhodná.HTTP requests should be independent and may occur in any order, so keeping transient state information between requests is not feasible. Je jediným místem, kde informace jsou uloženy v samotných zdrojích a každý požadavek by měl být atomické operace.The only place where information is stored is in the resources themselves, and each request should be an atomic operation. Toto omezení umožňuje webové služby za vysoce škálovatelné, protože není nutné možnost zachování všech vztahů mezi klienty a konkrétních serverů.This constraint enables web services to be highly scalable, because there is no need to retain any affinity between clients and specific servers. Jakýkoli server může zpracovat všechny žádosti od všech klientů.Any server can handle any request from any client. Ale nutné dodat, dalších faktorů může omezit škálovatelnost.That said, other factors can limit scalability. Například mnoho webových služeb zápis do úložiště dat back-end, který může být obtížné horizontální navýšení kapacity. (Článek vytvoření oddílů dat popisuje strategií horizontální navýšení kapacity úložiště dat.)For example, many web services write to a backend data store, which may be hard to scale out. (The article Data Partitioning describes strategies to scale out a data store.)

  • Rozhraní REST API se řídí hypermédií odkazy, které jsou obsaženy v rámci reprezentace.REST APIs are driven by hypermedia links that are contained in the representation. Následující příklad ukazuje reprezentaci JSON pořadí.For example, the following shows a JSON representation of an order. Obsahuje odkazy na získat nebo aktualizovat odběratele, související s pořadím.It contains links to get or update the customer associated with the order.

    {
        "orderID":3,
        "productID":2,
        "quantity":4,
        "orderValue":16.60,
        "links": [
            {"rel":"product","href":"http://adventure-works.com/customers/3", "action":"GET" },
            {"rel":"product","href":"http://adventure-works.com/customers/3", "action":"PUT" } 
        ]
    } 
    

V 2008, Leonardem Ryšánková navrhované následující vyspělosti modelu pro webové rozhraní API:In 2008, Leonard Richardson proposed the following maturity model for web APIs:

  • Úroveň 0: Definovat jeden identifikátor URI a všechny operace jsou požadavků POST na tento identifikátor URI.Level 0: Define one URI, and all operations are POST requests to this URI.
  • Úroveň 1: Vytvoření oddělte identifikátory URI pro jednotlivé prostředky.Level 1: Create separate URIs for individual resources.
  • Úroveň 2: Metody pomocí protokolu HTTP k definování operací s prostředky.Level 2: Use HTTP methods to define operations on resources.
  • Úroveň 3: Použijte hypermédií (HATEOAS popsané níže).Level 3: Use hypermedia (HATEOAS, described below).

Úroveň 3 odpovídá skutečně RESTful API podle definice Fielding společnosti.Level 3 corresponds to a truly RESTful API according to Fielding's definition. V praxi mnoho publikované webové rozhraní API spadají někde kolem úroveň 2.In practice, many published web APIs fall somewhere around level 2.

Uspořádání rozhraní API kolem prostředkyOrganize the API around resources

Soustředit na obchodní entity, které zpřístupní webové rozhraní API.Focus on the business entities that the web API exposes. V systému elektronické obchodování, primární entity může být například Zákazníci a objednávky.For example, in an e-commerce system, the primary entities might be customers and orders. Vytváření pořadí lze dosáhnout odesláním požadavek HTTP POST, který obsahuje informace o objednávce.Creating an order can be achieved by sending an HTTP POST request that contains the order information. Odpověď HTTP, která označuje, zda byla objednávka zadána úspěšně nebo ne.The HTTP response indicates whether the order was placed successfully or not. Pokud je to možné, identifikátory URI prostředku by měla vycházet z podstatná jména (prostředků) a příkazy (operace u prostředku).When possible, resource URIs should be based on nouns (the resource) and not verbs (the operations on the resource).

http://adventure-works.com/orders // Good

http://adventure-works.com/create-order // Avoid

Prostředek byl založen na jednotlivé položky fyzické nemá.A resource does not have to be based on a single physical data item. Prostředek pořadí může být například implementována interně jako několik tabulek v relační databázi, ale zobrazí klientovi jako jedna entita.For example, an order resource might be implemented internally as several tables in a relational database, but presented to the client as a single entity. Vyhněte se vytváření rozhraní API, která jednoduše zrcadlení interní databázi.Avoid creating APIs that simply mirror the internal structure of a database. Účelem REST je model entity a operace, které aplikace můžete provádět na tyto entity.The purpose of REST is to model entities and the operations that an application can perform on those entities. Klient by neměly být vystaveny pro interní implementaci.A client should not be exposed to the internal implementation.

Entity jsou často seskupeny do kolekcí (objednávky, zákazníků).Entities are often grouped together into collections (orders, customers). Kolekce je samostatný prostředků z položky v rámci kolekce a musí mít svůj vlastní identifikátor URI.A collection is a separate resource from the item within the collection, and should have its own URI. Následující identifikátor URI může například představují kolekci příkazů:For example, the following URI might represent the collection of orders:

http://adventure-works.com/orders

Odeslání požadavku HTTP GET do kolekce URI načte seznam položek v kolekci.Sending an HTTP GET request to the collection URI retrieves a list of items in the collection. Každá položka v kolekci má také svůj vlastní jedinečný identifikátor URI.Each item in the collection also has its own unique URI. Požadavek HTTP GET na identifikátor URI položky vrátí podrobnosti o této položce.An HTTP GET request to the item's URI returns the details of that item.

Přijmout konzistentní zásady vytváření názvů v identifikátory URI.Adopt a consistent naming convention in URIs. Obecně platí je dobré se tento odkaz kolekce použít pro identifikátory URI množném čísle podstatná jména.In general, it helps to use plural nouns for URIs that reference collections. Je dobrým zvykem uspořádání identifikátory URI pro kolekce a položky do hierarchie.It's a good practice to organize URIs for collections and items into a hierarchy. Například /customers je cesta ke kolekci zákazníků a /customers/5 je cesta k zákazník s ID rovná 5.For example, /customers is the path to the customers collection, and /customers/5 is the path to the customer with ID equal to 5. Tento přístup pomáhá chránit intuitivní webové rozhraní API.This approach helps to keep the web API intuitive. Navíc mnoho architektury webového rozhraní API může směrovat požadavků podle parametrizované cesty identifikátoru URI, takže můžete třeba definovat trasy pro cestu /customers/{id}.Also, many web API frameworks can route requests based on parameterized URI paths, so you could define a route for the path /customers/{id}.

Zvažte také vztahy mezi různé typy prostředků a jak mohou být vystaveny tyto přidružení.Also consider the relationships between different types of resources and how you might expose these associations. Například /customers/5/orders může představovat všechny objednávky zákazníka 5.For example, the /customers/5/orders might represent all of the orders for customer 5. Můžete také přejít v opačným směrem a představují přidružení od pořadí zpět na zákazníka s identifikátorem URI, jako /orders/99/customer.You could also go in the other direction, and represent the association from an order back to a customer with a URI such as /orders/99/customer. Rozšíření tento model příliš daleko, ale může stát náročná implementovat.However, extending this model too far can become cumbersome to implement. Lepším řešením je zajistit navigaci odkazy na související zdroje v těle zprávy s odpovědí HTTP.A better solution is to provide navigable links to associated resources in the body of the HTTP response message. Tento mechanismus je podrobně popsány v další části HATEOAS přístup k povolení navigace k související prostředky později.This mechanism is described in more detail in the section Using the HATEOAS Approach to Enable Navigation To Related Resources later.

V systémech složitější, může být tempting zajistit identifikátory URI, které umožňují klientovi procházet několik úrovní relace, jako například /customers/1/orders/99/products.In more complex systems, it can be tempting to provide URIs that enable a client to navigate through several levels of relationships, such as /customers/1/orders/99/products. Tato úroveň složitosti však může být poměrně složitá a je pevná, pokud v budoucnu změnit vztahy mezi prostředky.However, this level of complexity can be difficult to maintain and is inflexible if the relationships between resources change in the future. Místo toho zkuste zachovat poměrně jednoduché identifikátory URI.Instead, try to keep URIs relatively simple. Jakmile aplikace obsahuje odkaz na prostředek, musí být možné použít tento odkaz k nalezení položek související se tento prostředek.Once an application has a reference to a resource, it should be possible to use this reference to find items related to that resource. Předchozí dotaz lze nahradit s identifikátorem URI /customers/1/orders vyhledat objednávky pro zákazníka 1 a potom /orders/99/products najít produkty v tomto pořadí.The preceding query can be replaced with the URI /customers/1/orders to find all the orders for customer 1, and then /orders/99/products to find the products in this order.

Tip

Vyhněte se nutnosti prostředků identifikátory URI složitější než kolekce nebo nebo kolekce položek.Avoid requiring resource URIs more complex than collection/item/collection.

Dalším faktorem je, aby všechny webové požadavky použít zatížení na webovém serveru.Another factor is that all web requests impose a load on the web server. Další požadavky, tím větší zatížení.The more requests, the bigger the load. Proto pokuste se vyhnout "chatty" webového rozhraní API, která vystavit velké množství malých prostředky.Therefore, try to avoid "chatty" web APIs that expose a large number of small resources. Taková rozhraní API může vyžadovat odesílat více požadavků k vyhledání všech dat, která vyžaduje zadání klientské aplikace.Such an API may require a client application to send multiple requests to find all of the data that it requires. Místo toho můžete chtít denormalize data a související informace do větší prostředky, které mohou být načteny s jeden požadavek.Instead, you might want to denormalize the data and combine related information into bigger resources that can be retrieved with a single request. Ale musíte vyvážit tento přístup proti režií při načítání dat, která nepotřebuje klienta.However, you need to balance this approach against the overhead of fetching data that the client doesn't need. Načítání velkých objektů můžete zvýšit latence žádost a vynakládá dodatečnou šířku pásma.Retrieving large objects can increase the latency of a request and incur additional bandwidth costs. Další informace o těchto antipatterns výkonu najdete v tématu Chatty vstupně-výstupních operací a nadbytečné načítání.For more information about these performance antipatterns, see Chatty I/O and Extraneous Fetching.

Vyhněte se představení závislosti mezi webové rozhraní API a podkladových zdrojů dat.Avoid introducing dependencies between the web API and the underlying data sources. Například pokud vaše data uložena v relační databázi, webového rozhraní API není nutné vystavit tabulek v kolekci prostředků.For example, if your data is stored in a relational database, the web API doesn't need to expose each table as a collection of resources. Ve skutečnosti, který je pravděpodobně nízký návrhu.In fact, that's probably a poor design. Místo toho Považujte webové rozhraní API za abstrakci databáze.Instead, think of the web API as an abstraction of the database. V případě potřeby zavést vrstva mapování mezi databází a webové rozhraní API.If necessary, introduce a mapping layer between the database and the web API. Tímto způsobem klientské aplikace jsou izolované od změny na základní schéma databáze.That way, client applications are isolated from changes to the underlying database scheme.

Navíc nemusí být možné mapovat každé operace implementované webového rozhraní API pro konkrétní prostředek.Finally, it might not be possible to map every operation implemented by a web API to a specific resource. Lze například zpracovat jiných prostředků scénáře přes požadavky HTTP, které vyvolání funkce a vrátí výsledky jako zprávy odpovědi HTTP.You can handle such non-resource scenarios through HTTP requests that invoke a function and return the results as an HTTP response message. Webové rozhraní API, který implementuje jednoduché kalkulačky operací, jako sčítání a odečítání může například zadat identifikátory URI, který zveřejnění těchto operací jako pseudo prostředky a k určení parametrů požadovaných pomocí řetězce dotazu.For example, a web API that implements simple calculator operations such as add and subtract could provide URIs that expose these operations as pseudo resources and use the query string to specify the parameters required. Například požadavek GET na identifikátor URI / add? operand1 = 99 & operand2 = 1 by vrátit zprávu odpovědi subjektu, který obsahuje hodnotu 100.For example a GET request to the URI /add?operand1=99&operand2=1 would return a response message with the body containing the value 100. Však používejte pouze tyto formuláře identifikátory URI opatrně.However, only use these forms of URIs sparingly.

Definování operace z hlediska metody HTTPDefine operations in terms of HTTP methods

Protokol HTTP definuje několik metod, které význam sémantického přiřadit žádost.The HTTP protocol defines a number of methods that assign semantic meaning to a request. Běžné metody HTTP používá většina RESTful webová rozhraní API jsou:The common HTTP methods used by most RESTful web APIs are:

  • ZÍSKAT načte prostředek na zadaný identifikátor URI.GET retrieves a representation of the resource at the specified URI. Tělo zprávy odpovědi obsahuje podrobnosti o požadovaný prostředek.The body of the response message contains the details of the requested resource.
  • POST vytvoří nový prostředek na zadaný identifikátor URI.POST creates a new resource at the specified URI. Tělo zprávy požadavku poskytuje podrobnosti o nový prostředek.The body of the request message provides the details of the new resource. Všimněte si, že POST lze také spouštět operace, které nejsou ve skutečnosti vytvořit prostředky.Note that POST can also be used to trigger operations that don't actually create resources.
  • UVEĎTE vytvoří nebo nahrazuje prostředek na zadaný identifikátor URI.PUT either creates or replaces the resource at the specified URI. Tělo zprávy požadavku určuje prostředek pro vytvoření nebo aktualizaci.The body of the request message specifies the resource to be created or updated.
  • OPRAVA provede částečné aktualizace prostředku.PATCH performs a partial update of a resource. Text žádosti určuje sadu změn pro použití k prostředku.The request body specifies the set of changes to apply to the resource.
  • Odstranit odebere prostředek na zadaný identifikátor URI.DELETE removes the resource at the specified URI.

Účinek konkrétního požadavku by měl závisí na tom, zda je prostředek kolekci nebo jednotlivé položky.The effect of a specific request should depend on whether the resource is a collection or an individual item. Následující tabulka shrnuje běžné konvence přijat nejvíce RESTful implementace pomocí příklad elektronické obchodování.The following table summarizes the common conventions adopted by most RESTful implementations using the ecommerce example. Všimněte si, že ne všechny tyto požadavky se může implementovat; To závisí na konkrétní scénář.Note that not all of these requests might be implemented; it depends on the specific scenario.

ProstředekResource POSTPOST GETGET PUTPUT ODSTRANITDELETE
/Customers/customers Vytvoření nového odběrateleCreate a new customer Načíst všechny zákazníkyRetrieve all customers Hromadné aktualizace zákazníkůBulk update of customers Odeberte všechny zákazníkyRemove all customers
nebo zákazníků nebo 1/customers/1 ChybaError Načtení podrobností pro zákazníka 1Retrieve the details for customer 1 Aktualizovat podrobnosti o zákazníka 1, pokud existujeUpdate the details of customer 1 if it exists Odebrat odběratele 1Remove customer 1
/Customers/1/orders/customers/1/orders Vytvořit nové pořadí pro zákazníka 1Create a new order for customer 1 Načíst všechny objednávky pro zákazníka 1Retrieve all orders for customer 1 Hromadné aktualizace objednávek pro zákazníka 1Bulk update of orders for customer 1 Odeberte všechny objednávky pro zákazníka 1Remove all orders for customer 1

Rozdíly mezi POST, PUT a oprava může být matoucí.The differences between POST, PUT, and PATCH can be confusing.

  • Požadavek POST vytvoří prostředek.A POST request creates a resource. Server přiřadí identifikátor URI pro nový prostředek a vrátí tento identifikátor URI pro klienta.The server assigns a URI for the new resource, and returns that URI to the client. V modelu REST často vztahují požadavků POST na kolekce.In the REST model, you frequently apply POST requests to collections. Nový prostředek se přidá do kolekce.The new resource is added to the collection. Požadavek POST lze také odeslat data pro zpracování pro existující prostředek, bez jakékoli nový prostředek vytváří.A POST request can also be used to submit data for processing to an existing resource, without any new resource being created.

  • Požadavek PUT vytvoří prostředek nebo aktualizuje existující prostředek.A PUT request creates a resource or updates an existing resource. Klient určuje identifikátor URI pro prostředek.The client specifies the URI for the resource. Text žádosti obsahuje kompletní reprezentace prostředku.The request body contains a complete representation of the resource. Pokud prostředek s Tento identifikátor URI již existuje, je nahradit.If a resource with this URI already exists, it is replaced. V opačném případě je vytvořen nový prostředek, pokud je server podporuje, tak.Otherwise a new resource is created, if the server supports doing so. Požadavky PUT se nejčastěji používají ke prostředky, které jsou jednotlivé položky, jako je například konkrétního zákazníka, nikoli kolekce.PUT requests are most frequently applied to resources that are individual items, such as a specific customer, rather than collections. Server může podporovat aktualizace, ale není vytvoření prostřednictvím PUT.A server might support updates but not creation via PUT. Jestli se pro podporu vytváření prostřednictvím PUT, závisí na tom, jestli klient se může srozumitelně přiřadit identifikátoru URI prostředku před existuje.Whether to support creation via PUT depends on whether the client can meaningfully assign a URI to a resource before it exists. Pokud ne, pak pomocí po vytvoření prostředků a PUT nebo PATCH aktualizovat.If not, then use POST to create resources and PUT or PATCH to update.

  • Žádost o opravu provede částečné aktualizace pro existující prostředek.A PATCH request performs a partial update to an existing resource. Klient určuje identifikátor URI pro prostředek.The client specifies the URI for the resource. Text žádosti určuje sadu změny použít k prostředku.The request body specifies a set of changes to apply to the resource. To může být efektivnější než použití PUT, protože klient odešle pouze změny, ne celý reprezentace prostředku.This can be more efficient than using PUT, because the client only sends the changes, not the entire representation of the resource. Technicky opravy můžete také vytvořit nový prostředek (zadáním sadu aktualizací na "null" prostředek), pokud je server podporuje to.Technically PATCH can also create a new resource (by specifying a set of updates to a "null" resource), if the server supports this.

Požadavky PUT, musí být idempotent.PUT requests must be idempotent. Pokud klient odešle stejné žádosti PUT vícekrát, výsledky by měl být vždy stejné (stejného zdroje bude upraveno se stejnými hodnotami).If a client submits the same PUT request multiple times, the results should always be the same (the same resource will be modified with the same values). POST a oprava požadavky nemusí být idempotent.POST and PATCH requests are not guaranteed to be idempotent.

Sémantika HTTP v souladu sConform to HTTP semantics

Tato část popisuje některé typické důležité informace týkající se návrhu rozhraní API, který splňuje specifikace protokolu HTTP.This section describes some typical considerations for designing an API that conforms to the HTTP specification. Je však nezahrnuje všechny možné podrobnosti nebo scénář.However, it doesn't cover every possible detail or scenario. Pokud máte pochybnosti, poraďte se se specifikace protokolu HTTP.When in doubt, consult the HTTP specifications.

Typy médiíMedia types

Jak už bylo zmíněno dříve, klienti a servery exchange reprezentace prostředků.As mentioned earlier, clients and servers exchange representations of resources. Například v požadavku POST, text požadavku obsahuje prostředek pro vytvoření.For example, in a POST request, the request body contains a representation of the resource to create. Text odpovědi obsahuje načtených prostředek v požadavek GET.In a GET request, the response body contains a representation of the fetched resource.

V protokolu HTTP, jsou formáty zadaný prostřednictvím typy médií, označované taky jako typy MIME.In the HTTP protocol, formats are specified through the use of media types, also called MIME types. Pro data NEBINÁRNÍ většinu webové rozhraní API pro podporu JSON (typ média application/json =) a které by mohly mít XML (typ média = application/xml).For non-binary data, most web APIs support JSON (media type = application/json) and possibly XML (media type = application/xml).

Hlavička Content-Type v požadavku nebo odpovědi určuje formát reprezentace.The Content-Type header in a request or response specifies the format of the representation. Tady je příklad požadavek POST, která obsahuje JSON data:Here is an example of a POST request that includes JSON data:

POST http://adventure-works.com/orders HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Pokud server nepodporuje typ média, má být vrácen stavový kód HTTP 415 (nepodporovaný typ média).If the server doesn't support the media type, it should return HTTP status code 415 (Unsupported Media Type).

Požadavek klienta může obsahovat hlavičku Accept, který obsahuje seznam typů médií, klient přijme ze serveru ve zprávě s odpovědí.A client request can include an Accept header that contains a list of media types the client will accept from the server in the response message. Příklad:For example:

GET http://adventure-works.com/orders/2 HTTP/1.1
Accept: application/json

Pokud server se nemůže shodovat žádné z uvedených typů médií, má být vrácen stavový kód HTTP 406 (nepřijatelný).If the server cannot match any of the media type(s) listed, it should return HTTP status code 406 (Not Acceptable).

Metodám GETGET methods

Úspěšné metodu GET obvykle vrátí stavový kód HTTP 200 (OK).A successful GET method typically returns HTTP status code 200 (OK). Pokud prostředek nebyl nalezen, metoda by měla vrátit 404 (není nalezena).If the resource cannot be found, the method should return 404 (Not Found).

Metody POSTPOST methods

Pokud metodu POST vytvoří nový prostředek, vrátí stavový kód HTTP 201 (vytvořeno).If a POST method creates a new resource, it returns HTTP status code 201 (Created). Identifikátor URI nového prostředku je součástí umístění hlavičky odpovědi.The URI of the new resource is included in the Location header of the response. Text odpovědi obsahuje reprezentace prostředku.The response body contains a representation of the resource.

Pokud metoda nemá nějaké zpracování, ale nevytvoří nový prostředek, můžete metoda vrátí stavový kód HTTP 200 a zahrnout výsledek operace v textu odpovědi.If the method does some processing but does not create a new resource, the method can return HTTP status code 200 and include the result of the operation in the response body. Případně pokud neexistuje žádný výsledek určený k vrácení, metodu může vrátit stavový kód HTTP 204 (ne obsahu) s žádné odpovědi.Alternatively, if there is no result to return, the method can return HTTP status code 204 (No Content) with no response body.

Pokud klient: neplatná data vloží do požadavku, server by měl vrátit stavový kód HTTP 400 (Chybný požadavek).If the client puts invalid data into the request, the server should return HTTP status code 400 (Bad Request). Text odpovědi může obsahovat další informace o chybu nebo odkaz na identifikátor URI, který obsahuje další podrobnosti.The response body can contain additional information about the error or a link to a URI that provides more details.

PUT metodyPUT methods

Pokud metodu PUT vytvoří nový prostředek, vrátí stavový kód HTTP 201 (vytvořeno), stejně jako u metody POST.If a PUT method creates a new resource, it returns HTTP status code 201 (Created), as with a POST method. Pokud metoda aktualizuje existující prostředek, vrátí hodnotu 200 (OK) nebo 204 (ne obsahu).If the method updates an existing resource, it returns either 200 (OK) or 204 (No Content). V některých případech nemusí být možné aktualizovat existující prostředek.In some cases, it might not be possible to update an existing resource. V takovém případě zvažte vrátí stavový kód protokolu HTTP 409 (konflikt).In that case, consider returning HTTP status code 409 (Conflict).

Zvažte implementaci hromadné operace HTTP PUT, které můžete dávky aktualizace více prostředkům v kolekci.Consider implementing bulk HTTP PUT operations that can batch updates to multiple resources in a collection. Požadavek PUT musí určovat identifikátor URI kolekce a textu požadavku musí zadat podrobnosti o prostředky, které má být změněn.The PUT request should specify the URI of the collection, and the request body should specify the details of the resources to be modified. Tento přístup může pomoci snížit chattiness a zlepšíte výkon.This approach can help to reduce chattiness and improve performance.

Oprava metodyPATCH methods

Se žádostí o opravu, klient odešle sadu aktualizací do existující prostředek, ve formě oprava dokumentu.With a PATCH request, the client sends a set of updates to an existing resource, in the form of a patch document. Server zpracuje oprava dokument k provedení aktualizace.The server processes the patch document to perform the update. Oprava dokumentu popisuje celý prostředků pouze sadu změn pro použití.The patch document doesn't describe the whole resource, only a set of changes to apply. Specifikace pro metodu PATCH (RFC 5789) nedefinuje konkrétní formát pro dokumenty opravy.The specification for the PATCH method (RFC 5789) doesn't define a particular format for patch documents. Formát musí odvodit z typu média v požadavku.The format must be inferred from the media type in the request.

JSON je pravděpodobně nejběžnější formát dat pro webové rozhraní API.JSON is probably the most common data format for web APIs. Existují dva hlavní opravy na základě JSON formáty názvem JSON oprava a JSON sloučení oprava.There are two main JSON-based patch formats, called JSON patch and JSON merge patch.

Oprava sloučení JSON je poněkud jednodušší.JSON merge patch is somewhat simpler. Oprava dokument má stejnou strukturu jako původní prostředek JSON, ale zahrnuje jen dílčí sadu pole, která by měla být změněny nebo přidány.The patch document has the same structure as the original JSON resource, but includes just the subset of fields that should be changed or added. Kromě toho lze odstranit pole zadáním null pro hodnotu pole v dokumentu opravy.In addition, a field can be deleted by specifying null for the field value in the patch document. (To znamená, že oprava sloučení není vhodná, pokud na původní prostředek může mít explicitní hodnoty null.)(That means merge patch is not suitable if the original resource can have explicit null values.)

Předpokládejme například, že původní prostředek má následující reprezentace JSON:For example, suppose the original resource has the following JSON representation:

{ 
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

Zde je možné oprava sloučení JSON pro tento prostředek:Here is a possible JSON merge patch for this resource:

{ 
    "price":12,
    "color":null,
    "size":"small"
}

Tato hodnota informuje server aktualizujte "cena", "Barva" odstranit a přidejte "velikost".This tells the server to update "price", delete "color", and add "size". "Název" a "kategorie" se nemění."Name" and "category" are not modified. Přesné podrobnosti oprava sloučení JSON najdete v tématu RFC 7396.For the exact details of JSON merge patch, see RFC 7396. Typ média pro sloučení oprava JSON je "application/merge – oprava + json".The media type for JSON merge patch is "application/merge-patch+json".

Oprava sloučení není vhodná, pokud původní prostředků může obsahovat explicitní hodnoty null, z důvodu zvláštní význam null v dokumentu opravy.Merge patch is not suitable if the original resource can contain explicit null values, due to the special meaning of null in the patch document. Oprava dokumentu není také určit pořadí, že serveru by se měly používat aktualizace.Also, the patch document doesn't specify the order that the server should apply the updates. Který může nebo nemusí vás v závislosti na data a doméně.That may or may not matter, depending on the data and the domain. Oprava JSON, definované v RFC 6902, je flexibilnější.JSON patch, defined in RFC 6902, is more flexible. Jako posloupnost operací použít určuje změny.It specifies the changes as a sequence of operations to apply. Operace zahrnují přidat, odebrat, nahraďte, zkopírujte a testování (k ověření hodnoty).Operations include add, remove, replace, copy, and test (to validate values). Typ média pro oprava JSON je "application/json-patch + json".The media type for JSON patch is "application/json-patch+json".

Tady jsou některé typické chybové stavy, které může být došlo při zpracování požadavku PATCH, společně s odpovídající stavový kód HTTP.Here are some typical error conditions that might be encountered when processing a PATCH request, along with the appropriate HTTP status code.

Chybový stavError condition Stavový kód protokolu HTTPHTTP status code
Formát oprava dokument není podporovaný.The patch document format isn't supported. 415 (typ média není podporovaný.)415 (Unsupported Media Type)
Chybná oprava dokumentu.Malformed patch document. 400 (Chybný požadavek)400 (Bad Request)
Oprava dokumentu je platný, ale změny nelze použít k prostředku v jejím aktuálním stavu.The patch document is valid, but the changes can't be applied to the resource in its current state. 409 (konflikt)409 (Conflict)

Odstranit metodyDELETE methods

Pokud operace odstranění úspěšné, webový server by měl odpovídat stavový kód HTTP 204, která určuje, že proces byla úspěšně zpracována, ale že text odpovědi obsahuje žádné další informace.If the delete operation is successful, the web server should respond with HTTP status code 204, indicating that the process has been successfully handled, but that the response body contains no further information. Pokud prostředek neexistuje, můžete webový server vrátí chyby HTTP 404 (není nalezena).If the resource doesn't exist, the web server can return HTTP 404 (Not Found).

Asynchronní operaceAsynchronous operations

Operaci POST, PUT, PATCH nebo odstranit v některých případech může vyžadovat zpracování, která přebírá chvíli počkat na dokončení.Sometimes a POST, PUT, PATCH, or DELETE operation might require processing that takes awhile to complete. Pokud jste čekat na dokončení před odesláním odpovědi klientovi, může to způsobit nepřijatelné latence.If you wait for completion before sending a response to the client, it may cause unacceptable latency. Pokud ano, zvažte provedení asynchronní operaci.If so, consider making the operation asynchronous. Vrátí stavový kód HTTP 202 (platných) k označení na žádost byla přijata pro zpracování, ale není dokončena.Return HTTP status code 202 (Accepted) to indicate the request was accepted for processing but is not completed.

Koncový bod, který vrací stav Asynchronní požadavek, takže klient může sledovat stav pomocí cyklického dotazování na stav koncový bod musí vystavit.You should expose an endpoint that returns the status of an asynchronous request, so the client can monitor the status by polling the status endpoint. Zahrňte identifikátor URI koncového bodu stavu hlavička umístění 202 odpovědi.Include the URI of the status endpoint in the Location header of the 202 response. Příklad:For example:

HTTP/1.1 202 Accepted
Location: /api/status/12345

Pokud klient odešle požadavek GET na tento koncový bod, odpověď by měla obsahovat aktuální stav žádosti.If the client sends a GET request to this endpoint, the response should contain the current status of the request. Volitelně může obsahovat také odhadovaný čas dokončení nebo odkaz na tlačítko Storno.Optionally, it could also include an estimated time to completion or a link to cancel the operation.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345"
}

Pokud asynchronní operace vytvoří nový prostředek, stav koncového bodu má návratový stav code 303 (viz další) po dokončení operace.If the asynchronous operation creates a new resource, the status endpoint should return status code 303 (See Other) after the operation completes. V odpovědi 303 patří hlavičku umístění, která obsahuje identifikátor URI nového prostředku:In the 303 response, include a Location header that gives the URI of the new resource:

HTTP/1.1 303 See Other
Location: /api/orders/12345

Další informace najdete v tématu asynchronních operací v REST.For more information, see Asynchronous operations in REST.

Filtrování a stránkování datFilter and paginate data

Vystavení kolekce prostředků prostřednictvím jednoho identifikátoru URI může vést k načítání velkých objemů dat, pokud je nutný pouze část informací o aplikace.Exposing a collection of resources through a single URI can lead to applications fetching large amounts of data when only a subset of the information is required. Předpokládejme například, že klientská aplikace musí vyhledat objednávky s náklady přes konkrétní hodnotu.For example, suppose a client application needs to find all orders with a cost over a specific value. Je může načíst všechny objednávky z /řadí URI a vyfiltrujte tyto objednávky na straně klienta.It might retrieve all orders from the /orders URI and then filter these orders on the client side. Tento proces je jasně vysoce neefektivní.Clearly this process is highly inefficient. Na serveru, který hostuje webové rozhraní API se zbytečně plýtvá šířky pásma a možnosti výkonu sítě.It wastes network bandwidth and processing power on the server hosting the web API.

Místo toho rozhraní API můžete povolit předání filtru v řetězci dotazu identifikátoru URI, jako například /řadí? minCost = n.Instead, the API can allow passing a filter in the query string of the URI, such as /orders?minCost=n. Webové rozhraní API je poté zodpovědný za analýzy a zpracování minCost parametr v řetězci dotazu a vrácení filtrované výsledky na straně serveru.The web API is then responsible for parsing and handling the minCost parameter in the query string and returning the filtered results on the sever side.

Požadavky GET přes prostředky kolekce může vrátit potenciálně velký počet položek.GET requests over collection resources can potentially return a large number of items. Měli byste navrhnout webového rozhraní API pro omezení množství dat vrácených žádné jedné žádosti.You should design a web API to limit the amount of data returned by any single request. Vezměte v úvahu podpora řetězce dotazu, které určete maximální počet položek k načtení a počáteční posun do kolekce.Consider supporting query strings that specify the maximum number of items to retrieve and a starting offset into the collection. Příklad:For example:

/orders?limit=25&offset=50

Zvažte taky nastavení horní limit počtu položek vrácených, aby se zabránilo útokům Denial of Service.Also consider imposing an upper limit on the number of items returned, to help prevent Denial of Service attacks. Pomáhá klientské aplikace, získat požadavků, které mají být návratové stránkované data také obsahovat určitou formu metadata indikující celkový počet prostředků, které jsou k dispozici v kolekci.To assist client applications, GET requests that return paginated data should also include some form of metadata that indicate the total number of resources available in the collection. Můžete také zvážit další inteligentního stránkování strategie; Další informace najdete v tématu poznámky k návrhu rozhraní API: inteligentního stránkováníYou might also consider other intelligent paging strategies; for more information, see API Design Notes: Smart Paging

Strategie podobné můžete použít k řazení dat, jako jsou načtena tím, že poskytuje řazení parametr, který přebírá název pole jako hodnotu, jako například /řadí? řazení = ProductID.You can use a similar strategy to sort data as it is fetched, by providing a sort parameter that takes a field name as the value, such as /orders?sort=ProductID. Tento postup však může mít negativní vliv na ukládání do mezipaměti, protože identifikátor prostředku, který používá mnoho implementací mezipaměti jako klíč pro data uložená v mezipaměti součástí parametrů řetězce dotazu.However, this approach can have a negative effect on caching, because query string parameters form part of the resource identifier used by many cache implementations as the key to cached data.

Tento přístup k omezení pole pro každou položku je vrácena, pokud každá položka obsahuje velké množství dat můžete rozšířit.You can extend this approach to limit the fields returned for each item, if each item contains a large amount of data. Můžete například použít parametr řetězce dotazu, který přijímá čárkami oddělený seznam polí, jako například /řadí? pole = ProductID, množství.For example, you could use a query string parameter that accepts a comma-delimited list of fields, such as /orders?fields=ProductID,Quantity.

Zadejte všechny volitelné parametry v řetězcích dotazů smysluplný výchozí hodnoty.Give all optional parameters in query strings meaningful defaults. Například nastavit limit parametru 10 a offset parametru na hodnotu 0 Pokud implementaci stránkování, nastavte parametr řazení ke klíči prostředku, pokud budete implementovat, řazení a nastavte fields parametr pro všechna pole v prostředku Pokud jste Podpora projekce.For example, set the limit parameter to 10 and the offset parameter to 0 if you implement pagination, set the sort parameter to the key of the resource if you implement ordering, and set the fields parameter to all fields in the resource if you support projections.

Podpora částečné odpovědi pro velké binární prostředkySupport partial responses for large binary resources

Prostředek může obsahovat velká binární pole, například soubory nebo obrázky.A resource may contain large binary fields, such as files or images. Abyste vyřešili problémy způsobeno podle nespolehlivé a přerušované připojení a vylepšovat dobu odezvy, zvažte povolení těchto zdrojů k načtení v bloků.To overcome problems caused by unreliable and intermittent connections and to improve response times, consider enabling such resources to be retrieved in chunks. K tomuto účelu webové rozhraní API podporuje hlavičky Accept-rozsahy pro požadavky GET pro velké prostředky.To do this, the web API should support the Accept-Ranges header for GET requests for large resources. Tuto hlavičku označuje, že operace GET podporuje částečné požadavky.This header indicates that the GET operation supports partial requests. Klientská aplikace může odesílat požadavky GET, které vrátí podmnožinu prostředků, zadaný jako řadu bajtů.The client application can submit GET requests that return a subset of a resource, specified as a range of bytes.

Zvažte také implementace žádosti HTTP HEAD pro tyto prostředky.Also, consider implementing HTTP HEAD requests for these resources. Žádost HEAD je podobná požadavek GET s tím rozdílem, že vrátí pouze hlavičky protokolu HTTP, které vám vysvětlí, prostředku s tělo zprávy prázdný.A HEAD request is similar to a GET request, except that it only returns the HTTP headers that describe the resource, with an empty message body. Klientská aplikace můžete vydat žádost HEAD k určení, jestli se má načíst prostředek pomocí částečné požadavky GET.A client application can issue a HEAD request to determine whether to fetch a resource by using partial GET requests. Příklad:For example:

HEAD http://adventure-works.com/products/10?fields=productImage HTTP/1.1

Tady je zprávu odpovědi na příkladu:Here is an example response message:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

Hlavičku Content-Length dává celková velikost prostředku a hlavičky Accept-rozsahy označuje, že odpovídající operaci GET podporuje částečné výsledky.The Content-Length header gives the total size of the resource, and the Accept-Ranges header indicates that the corresponding GET operation supports partial results. Klientská aplikace můžete použít tyto informace k načtení obrázku v menší skupiny.The client application can use this information to retrieve the image in smaller chunks. První požadavek načte první 2 500 bajtů pomocí hlavičky Range:The first request fetches the first 2500 bytes by using the Range header:

GET http://adventure-works.com/products/10?fields=productImage HTTP/1.1
Range: bytes=0-2499

Zpráva odpovědi označuje, že to je částečné odpovědi vrácením stavový kód HTTP 206.The response message indicates that this is a partial response by returning HTTP status code 206. Hlavičku Content-Length určuje skutečný počet bajtů vrácených v textu zprávy (ne podle velikosti vytvořeného prostředku), a hlavičku Content-Range označuje, která část prostředku jde (bajtů 0 2499 mimo 4580):The Content-Length header specifies the actual number of bytes returned in the message body (not the size of the resource), and the Content-Range header indicates which part of the resource this is (bytes 0-2499 out of 4580):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

Následné žádosti z klienta aplikace můžete načíst zbytek prostředku.A subsequent request from the client application can retrieve the remainder of the resource.

Jedním z primární motivace za REST je, že by měl být možné přejít celá sada prostředky bez nutnosti předchozí znalosti schéma identifikátoru URI.One of the primary motivations behind REST is that it should be possible to navigate the entire set of resources without requiring prior knowledge of the URI scheme. Každý požadavek HTTP GET by měla vrátit informace potřebné k vyhledávání prostředků souvisejících s přímo na požadovaný objekt prostřednictvím hypertextové odkazy, které jsou zahrnuty v odpovědi a musí zadat i s informacemi, které popisuje operace, které jsou k dispozici na Každý z těchto prostředků.Each HTTP GET request should return the information necessary to find the resources related directly to the requested object through hyperlinks included in the response, and it should also be provided with information that describes the operations available on each of these resources. Tato zásada se označuje jako HATEOAS nebo Hypertext jako modul stavu aplikace.This principle is known as HATEOAS, or Hypertext as the Engine of Application State. Systém je efektivně konečný stav počítače, a odpověď na každý požadavek obsahuje informace potřebné k přesunuty z jednoho stavu do jiného; žádné jiné informace by měly být nutné.The system is effectively a finite state machine, and the response to each request contains the information necessary to move from one state to another; no other information should be necessary.

Poznámka

Aktuálně neexistují žádné standardy nebo specifikace, které definovat, jak model Princip HATEOAS.Currently there are no standards or specifications that define how to model the HATEOAS principle. Příklady uvedené v této části ilustrují jedním z možných řešení.The examples shown in this section illustrate one possible solution.

Pro zpracování vztah mezi pořadí a zákazníka, například reprezentace pořadí můžou zahrnovat odkazy, které určují dostupné operací zákazníka pořadí.For example, to handle the relationship between an order and a customer, the representation of an order could include links that identify the available operations for the customer of the order. Zde je možné reprezentace:Here is a possible representation:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"http://adventure-works.com/customers/3", 
      "action":"GET",
      "types":["text/xml","application/json"] 
    },
    {
      "rel":"customer",
      "href":"http://adventure-works.com/customers/3", 
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"http://adventure-works.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"http://adventure-works.com/orders/3", 
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"http://adventure-works.com/orders/3", 
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"http://adventure-works.com/orders/3", 
      "action":"DELETE",
      "types":[]
    }]
}

V tomto příkladu links pole obsahuje sadu odkazy.In this example, the links array has a set of links. Každé propojení představuje operace na související entity.Each link represents an operation on a related entity. Data pro každý odkaz zahrnuje relaci ("zákazník"), identifikátor URI (http://adventure-works.com/customers/3), metoda HTTP a podporované typy MIME.The data for each link includes the relationship ("customer"), the URI (http://adventure-works.com/customers/3), the HTTP method, and the supported MIME types. Toto je veškeré informace, které klientské aplikace potřebuje k vyvolání operace.This is all the information that a client application needs to be able to invoke the operation.

links Pole obsahuje také odkazující samy na sebe informace o prostředek sám sebe, který byl načteny.The links array also includes self-referencing information about the resource itself that has been retrieved. Tyto mít relace vlastní.These have the relationship self.

Sada odkazy, které jsou vráceny se může změnit v závislosti na stavu prostředku.The set of links that are returned may change, depending on the state of the resource. Toto je pojmy hypertext se "modul stavu aplikace."This is what is meant by hypertext being the "engine of application state."

Správa verzí RESTful webového rozhraní APIVersioning a RESTful web API

Je vysoce nepravděpodobné, že webového rozhraní API bude zůstat statický.It is highly unlikely that a web API will remain static. Mění obchodní požadavky nové kolekce prostředky, které mohou být přidány, vztahy mezi prostředky mohou změnit a může být změněna strukturu dat v prostředky.As business requirements change new collections of resources may be added, the relationships between resources might change, and the structure of the data in resources might be amended. Při aktualizaci webové rozhraní API pro zpracování požadavků na nové nebo různé je poměrně jednoduchý proces, musíte zvážit důsledky, které tyto změny budou mít na klientské aplikace využívají webové rozhraní API.While updating a web API to handle new or differing requirements is a relatively straightforward process, you must consider the effects that such changes will have on client applications consuming the web API. Problém je, i když vývojáři navrhování a implementace rozhraní web API má plnou kontrolu nad toto rozhraní API, vývojář nemá stejnou úrovní kontrolu nad klientské aplikace, které může být vytvořené třetí strany organizace operační vzdáleně.The issue is that although the developer designing and implementing a web API has full control over that API, the developer does not have the same degree of control over client applications which may be built by third party organizations operating remotely. Primární imperativní je umožnit existující klientské aplikace, aby fungovaly i beze změny současně nového klienta aplikace, abyste mohli využívat nové funkce a prostředků.The primary imperative is to enable existing client applications to continue functioning unchanged while allowing new client applications to take advantage of new features and resources.

Správa verzí umožňuje webového rozhraní API označíte, funkce a prostředky, které vystavuje a klientské aplikace mohou odesílat požadavky, které jsou směrované na konkrétní verzi funkce nebo prostředků.Versioning enables a web API to indicate the features and resources that it exposes, and a client application can submit requests that are directed to a specific version of a feature or resource. Následující části popisují několik různý přístup, z nichž každá má své výhody a kompromis.The following sections describe several different approaches, each of which has its own benefits and trade-offs.

Bez správy verzíNo versioning

Toto je nejjednodušší přístup a může být přijatelné pro některé interní rozhraní API.This is the simplest approach, and may be acceptable for some internal APIs. Big změny může být reprezentován jako nových prostředků nebo nové odkazy.Big changes could be represented as new resources or new links. Přidávání obsahu do existujících prostředků nemusí nabízet narušující změně v klientských aplikací, které nejsou správná, že tento obsah se jednoduše ho ignorovat.Adding content to existing resources might not present a breaking change as client applications that are not expecting to see this content will simply ignore it.

Například požadavek na identifikátor URI http://adventure-works.com/customers/3 by měla vrátit podrobnosti jednoho zákazníka obsahující id, name, a address pole očekávanou klientské aplikace :For example, a request to the URI http://adventure-works.com/customers/3 should return the details of a single customer containing id, name, and address fields expected by the client application:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

Poznámka

Pro jednoduchost příklad odpovědi uvedené v této části nezahrnují HATEOAS odkazy.For simplicity, the example responses shown in this section do not include HATEOAS links.

Pokud DateCreated pole je přidáno do schématu prostředku zákazníka a pak odpověď bude vypadat takto:If the DateCreated field is added to the schema of the customer resource, then the response would look like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

Existující klientské aplikace může dál fungovat správně, pokud je může ignorování nerozpoznaná pole, zatímco nové klientské aplikace mohou být navržena pro zpracování této nové pole.Existing client applications might continue functioning correctly if they are capable of ignoring unrecognized fields, while new client applications can be designed to handle this new field. Ale pokud dojde k více znak změny schématu prostředků (například odebrání nebo přejmenování polí), nebo změňte vztahy mezi prostředky pak tyto může představovat nejnovější změny, které zabraňují existující klientské aplikace nebude fungovat správně .However, if more radical changes to the schema of resources occur (such as removing or renaming fields) or the relationships between resources change then these may constitute breaking changes that prevent existing client applications from functioning correctly. V těchto situacích zvažte jednu z následujících dvou přístupů.In these situations you should consider one of the following approaches.

Identifikátor URI Správa verzíURI versioning

Pokaždé, když upravíte webové rozhraní API nebo změnit schéma prostředky, přidejte číslo verze na identifikátor URI pro každého prostředku.Each time you modify the web API or change the schema of resources, you add a version number to the URI for each resource. Dříve existující identifikátory URI by měly být nadále fungovat jako předtím vrácení prostředky, které odpovídají do jejich původního schématu.The previously existing URIs should continue to operate as before, returning resources that conform to their original schema.

Rozšíření na předchozí příklad, pokud address pole je změnili do každé základní část adresy obsahující dílčí pole (například streetAddress, city, state, a zipCode), může být tato verze prostředku k dispozici prostřednictvím identifikátoru URI obsahující číslo verze, jako je například http://adventure-works.com/v2/customers/3:Extending the previous example, if the address field is restructured into sub-fields containing each constituent part of the address (such as streetAddress, city, state, and zipCode), this version of the resource could be exposed through a URI containing a version number, such as http://adventure-works.com/v2/customers/3:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Tento mechanismus správy verzí je velmi jednoduchý, ale závisí na serveru pro směrování požadavku na příslušný koncový bod.This versioning mechanism is very simple but depends on the server routing the request to the appropriate endpoint. Ale může stát nepraktické jako webová rozhraní API existence prostřednictvím několika iterací a server musí podporovat několik různých verzí.However, it can become unwieldy as the web API matures through several iterations and the server has to support a number of different versions. Navíc z purist ve všech případech klientské aplikace jsou načítání stejná data (odběratel 3), takže identifikátor URI by nemělo být skutečně liší v závislosti na verzi.Also, from a purist’s point of view, in all cases the client applications are fetching the same data (customer 3), so the URI should not really be different depending on the version. Toto schéma také komplikuje implementace HATEOAS jako všechny odkazy, se musí obsahovat číslo verze v jejich identifikátory URI.This scheme also complicates implementation of HATEOAS as all links will need to include the version number in their URIs.

Správa verzí řetězec dotazuQuery string versioning

Místo poskytuje více identifikátory URI, můžete zadat verzi prostředku pomocí parametr řetězce dotazu, připojí k požadavku HTTP, jako například http://adventure-works.com/customers/3?version=2.Rather than providing multiple URIs, you can specify the version of the resource by using a parameter within the query string appended to the HTTP request, such as http://adventure-works.com/customers/3?version=2. Parametr verze by měl výchozí hodnotu smysluplný například 1, pokud je vynechán starší klientské aplikace.The version parameter should default to a meaningful value such as 1 if it is omitted by older client applications.

Tento přístup má výhodu sémantického, která stejného zdroje se vždy načítají stejným identifikátorem URI, ale závisí na kód, který zpracovává požadavek na analyzovat řetězec dotazu a odeslat zpět odpovídající odpověď HTTP.This approach has the semantic advantage that the same resource is always retrieved from the same URI, but it depends on the code that handles the request to parse the query string and send back the appropriate HTTP response. Tento přístup také vykazuje stejný komplikace pro implementaci HATEOAS jako mechanismus Správa verzí identifikátor URI.This approach also suffers from the same complications for implementing HATEOAS as the URI versioning mechanism.

Poznámka

Některé starší webových prohlížečů a webové proxy servery nebude ukládat do mezipaměti odpovědi pro požadavky, které obsahují řetězec dotazu v identifikátoru URI.Some older web browsers and web proxies will not cache responses for requests that include a query string in the URI. To může mít negativní dopad na výkon pro webové aplikace, které využívají webové rozhraní API a který spustit z webového prohlížeče.This can have an adverse impact on performance for web applications that use a web API and that run from within such a web browser.

Správa verzí hlavičkyHeader versioning

Místo přidávání číslo verze jako parametr řetězce dotazu, může implementovat vlastní hlavičky, která určuje verzi prostředku.Rather than appending the version number as a query string parameter, you could implement a custom header that indicates the version of the resource. Tento přístup vyžaduje, aby klientská aplikace přidá odpovídající hlavičku všechny žádosti, i když kód, který zpracovává požadavek klienta použít výchozí hodnotu (verze 1) Pokud je vynechán hlavičku verze.This approach requires that the client application adds the appropriate header to any requests, although the code handling the client request could use a default value (version 1) if the version header is omitted. Následující příklady využívat vlastní hlavičku s názvem vlastní hlavičku.The following examples utilize a custom header named Custom-Header. Hodnotu této hlavičky určuje verzi rozhraní web API.The value of this header indicates the version of web API.

Verze 1:Version 1:

GET http://adventure-works.com/customers/3 HTTP/1.1
Custom-Header: api-version=1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

Verze 2:Version 2:

GET http://adventure-works.com/customers/3 HTTP/1.1
Custom-Header: api-version=2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Všimněte si, že stejně jako u předchozí dva přístupy, implementace HATEOAS vyžaduje včetně odpovídající vlastní hlavičky v jakékoli odkazy.Note that as with the previous two approaches, implementing HATEOAS requires including the appropriate custom header in any links.

Typ média, Správa verzíMedia type versioning

Když klientské aplikace odešle požadavek HTTP GET na webový server by měl ho stanovení formát obsah, který dokáže zpracovat pomocí hlavičky Accept, jak je popsáno výše v tomto návodu.When a client application sends an HTTP GET request to a web server it should stipulate the format of the content that it can handle by using an Accept header, as described earlier in this guidance. Často účel přijmout záhlaví je umožnit klientská aplikace k určení, zda má být text odpovědi, XML, JSON nebo některé běžný formát, který lze analyzovat klienta.Frequently the purpose of the Accept header is to allow the client application to specify whether the body of the response should be XML, JSON, or some other common format that the client can parse. Nicméně je možné definovat vlastní média typy, které obsahují informace o povolení klientská aplikace k označení, která verze prostředku, který je očekáván.However, it is possible to define custom media types that include information enabling the client application to indicate which version of a resource it is expecting. Následující příklad ukazuje požadavek, který určuje přijmout záhlaví s hodnotou application/vnd.adventure-works.v1+json.The following example shows a request that specifies an Accept header with the value application/vnd.adventure-works.v1+json. Vnd.adventure works.v1 element na webový server označuje, že má být vrácen verze 1 prostředku, zatímco json element určuje, že JSON by měl být ve formátu textu odpovědi na:The vnd.adventure-works.v1 element indicates to the web server that it should return version 1 of the resource, while the json element specifies that the format of the response body should be JSON:

GET http://adventure-works.com/customers/3 HTTP/1.1
Accept: application/vnd.adventure-works.v1+json

Kód, který zpracovává požadavek je zodpovědná za zpracování přijmout záhlaví a aby byla dodržena Pokud je to možné (klientská aplikace může určovat více formátech v přijmout záhlaví, v takovém případě webový server můžete zvolit nejvhodnější formát pro text odpovědi).The code handling the request is responsible for processing the Accept header and honoring it as far as possible (the client application may specify multiple formats in the Accept header, in which case the web server can choose the most appropriate format for the response body). Webový server potvrdí formátu dat v textu odpovědi pomocí hlavičku Content-Type:The web server confirms the format of the data in the response body by using the Content-Type header:

HTTP/1.1 200 OK
Content-Type: application/vnd.adventure-works.v1+json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

Pokud hlavička Accept neurčuje žádné typy známé médií, webový server může vygenerovat zprávu odpovědi HTTP 406 (nepřijatelný) nebo vrátí zprávu s výchozí typ média.If the Accept header does not specify any known media types, the web server could generate an HTTP 406 (Not Acceptable) response message or return a message with a default media type.

Tento přístup je pravděpodobně purest mechanismů Správa verzí a poskytuje vlastní přirozeně HATEOAS, která může zahrnovat typ MIME souvisejících dat v odkazy na zdroje.This approach is arguably the purest of the versioning mechanisms and lends itself naturally to HATEOAS, which can include the MIME type of related data in resource links.

Poznámka

Když vyberete strategie správy verzí, jste měli také zvážit dopad na výkon, hlavně ukládání do mezipaměti na webovém serveru.When you select a versioning strategy, you should also consider the implications on performance, especially caching on the web server. Správa verzí URI a schémata Správa verzí řetězec dotazu jsou mezipaměti friendly, protože kombinace řetězec stejný dotaz v identifikátoru URI nebo odkazuje na stejná data pokaždé, když.The URI versioning and Query String versioning schemes are cache-friendly inasmuch as the same URI/query string combination refers to the same data each time.

Správa verzí hlavičky a typ média Správa verzí mechanismy obvykle vyžadují další logiku a zkontrolujte hodnoty v hlavičce vlastní nebo Hlavička Accept.The Header versioning and Media Type versioning mechanisms typically require additional logic to examine the values in the custom header or the Accept header. V prostředí rozsáhlých mnoho klientů pomocí různých verzích webového rozhraní API může způsobit významné množství duplicitní data v mezipaměti na straně serveru.In a large-scale environment, many clients using different versions of a web API can result in a significant amount of duplicated data in a server-side cache. Tento problém se může stát čárkou nad vpravo, klientská aplikace komunikuje se serverem webové prostřednictvím proxy serveru, který implementuje ukládání do mezipaměti, a který pouze předá požadavek na webový server, pokud ji nemá aktuálně kopii požadovaná data v mezipaměti.This issue can become acute if a client application communicates with a web server through a proxy that implements caching, and that only forwards a request to the web server if it does not currently hold a copy of the requested data in its cache.

Otevřete Initiative rozhraní APIOpen API Initiative

Otevřené rozhraní API Initiative byl vytvořen konsorciem odvětví standardizace popisy rozhraní REST API přes dodavatele.The Open API Initiative was created by an industry consortium to standardize REST API descriptions across vendors. V rámci této iniciativy specifikace Swagger 2.0 byl přejmenován specifikace OpenAPI (OAS) a dát otevřete Initiative rozhraní API.As part of this initiative, the Swagger 2.0 specification was renamed the OpenAPI Specification (OAS) and brought under the Open API Initiative.

Můžete přijmout OpenAPI pro webového rozhraní API.You may want to adopt OpenAPI for your web APIs. Některé body vzít v úvahu:Some points to consider:

  • Specifikace OpenAPI obsahuje sadu zaujatých pokyny na tom, jak by se měly navrhovat rozhraní REST API.The OpenAPI Specification comes with a set of opinionated guidelines on how a REST API should be designed. Které má výhod pro spolupráci, ale vyžaduje další pozor při navrhování tak, aby odpovídala specifikace rozhraní API.That has advantages for interoperability, but requires more care when designing your API to conform to the specification.
  • OpenAPI podporuje přístup první kontrakt, nikoli implementace první přístup.OpenAPI promotes a contract-first approach, rather than an implementation-first approach. Kontrakt první znamená návrh rozhraní API nejprve smlouvy (rozhraní) a pak napsat kód, který implementuje kontrakt.Contract-first means you design the API contract (the interface) first and then write code that implements the contract.
  • Nástroje, například Swagger můžete z rozhraní API kontrakty vygenerovat knihovny klienta nebo v dokumentaci.Tools like Swagger can generate client libraries or documentation from API contracts. Například v tématu rozhraní ASP.NET Web API pomůže Pages pomocí Swagger.For example, see ASP.NET Web API Help Pages using Swagger.

Další informaceMore information