« 英文で読むITポリシー「Angular vs React」 | Main | 英語で読むITポリシー「RFC1958」 »

2018.09.16

英語で読むITポリシー「API」

quote for TOEICは古典的な話だけでなく現代的なポリシーからも引用している。若干のブームは過ぎてしまった感があるが、各社がこぞってAPIを公開し、同時に自社のAPIには一貫性があって使いやすいことを競うように啓蒙していた。そこでMicrosoftとGoogleのAPIに関するガイドラインから引用する。

まず、Microsoft。HTTPメソッドでGETとPOSTは有名だが、それ以外にもPUTやPATCH、DELETEを使うということを規定している。

The HTTP protocol defines a number of methods that assign semantic meaning to a request. The common HTTP methods used by most RESTful web APIs are: GET/POST/PUT/PATCH/DELETE

次にGoogleのAPI Design Guide。こちらも言ってることは同じ。別にMicrosoftとGoogleが仲がいいというわけではなく、両者ともRoy Fieldingの2000年の博士論文に端を発するRESTの思想を忠実に継承しているということだ。

The resources and methods are known as nouns and verbs of APIs. With the HTTP protocol, the resource names naturally map to URLs, and methods naturally map to HTTP methods POST, GET, PUT, PATCH, and DELETE.

MicrosoftもGoogleもメンバーであるOpenAPI Initiativeという標準化団体はOpenAPI Specification 3.0.1で次のように書いている。

The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.

RFC7231だとGET/POST/PUT/PATCH/DELETEに加え、CONNECT/OPTIONS/TRACEが加わるが、実質、同じことを言ってると思って間違いない。

次にURIについて。Googleは「DNS-compatible」でリソースを相対的に表現することとしている。

A scheme-less URI consisting of a DNS-compatible API service name and a resource path. The resource path is also known as relative resource name. For example: "//library.googleapis.com/shelves/shelf1/books/book2"

一方のMicrosoftは、単一の物理データに依存する必要はないと言っている。Googleのshelves/shelf1/books/book2という例でいうと、bookはshelfにあってもいいけど、別にshopでもlibraryでもいいよね、ということかな。

A resource does not have to be based on a single physical data item. 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.

OpenAPIは歯切れが悪い。Micsosoftに「単一の物理データに紐付かなくてもいいよね」という態度を取ってしまった以上、共通的に括れるのは文字種だけになってしまったのかもしれない。

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Relative references are resolved using the URLs defined in the Server Object as a Base URI.

GoogleもMicrosoftもOpenAPI Initiativeに参画しながら独自のAPIポリシーを策定しているのは、一見してわからないような根が深い差分があるということだろう。水野貴明さんの「Web API: The Good Parts」はTwitterやFacebookのガイドラインまで含め、APIと一口に言っても実に色々なパターンがあることがわかり、読んでて楽しい。

それとも、GoogleはgRPCを、MicrosoftはODataを引っ張るため、今となっては中途半端なHTTP1.Xベースの標準化にリソースを割いてる場合ではないということか。

|

« 英文で読むITポリシー「Angular vs React」 | Main | 英語で読むITポリシー「RFC1958」 »

英語で読むITポリシー」カテゴリの記事