必要な情報は何か。

前回まで

http://ytyaru.hatenablog.com/entry/2017/10/15/000000

おおまかな方針は決まった。

API用DB

以前、API用DBを作った。

GitHub.ApiEndpoint.Database.Create.20170124085656531

create table Apis(
    Id                  integer primary key,
    Name                text unique not null,
    HttpMethod          text not null check(HttpMethod='GET' or HttpMethod='POST' or HttpMethod='DELETE' or HttpMethod='PATCH' or HttpMethod='HEAD' or HttpMethod='PUT' or HttpMethod='OPTIONS' or HttpMethod='TRACE' or HttpMethod='LINK' or HttpMethod='UNLINK'),
    Endpoint            text not null,
    AuthMethods         text not null,
    Grants              text,
    SuccessStatusCode   integer check(100<=SuccessStatusCode and SuccessStatusCode<=599),
    DocumentUrl         text
);

できること

APIを一意に特定する
- HttpMethod
- Endpoint
必要な認証設定をする
- AuthMethods
必要なscopeをもったTokenを取得する
- Grants
成功時以外のときに例外発生させる
- SuccessStatusCode

不足している項目

HTTP
- Request
  - Header
    - Accept
  - Parameter
- Response
  - Header
    - Link
      - ページネーションの有無
    - MimeType
      - text, binary, json, …

本当非必要かどうかもわからない。具体的にどの処理をどう共通化するか先に考えておかないと。

項目	作業
Accept追加	マスターDBも必要？
Parameter	自動化はむずかしい？
ページネーション	DBで保持せず実装時にコードを書けばいい？
MimeType	HttpResponse、GitHubAPI、requestsライブラリの仕様を調査する必要がある？

Accept

Acceptを指定せねばリクエスト内容を特定できない場合がある。

たとえばライセンス情報を取得するにはHTTPヘッダのAcceptキー値をapplication/vnd.github.drax-preview+jsonにする必要がある。なければライセンス情報が取得できない。

Parameter

パラメータは自動化が難しいかもしれない。リポジトリ一覧取得などは引数の組合せ次第ではエラーになる場合もあるが、仕様書には自然言語で書かれている。これはプログラミングで実装するしかない。DBにデータとするには、自然言語を解読せねばならず、自動化が難しい。

たとえばリポジトリ一覧取得APIの引数typeはvisibility,affiliationと同時に使うと422エラーとなる。

Response

何を、どこから、どうやって取得するかを、APIごとに特定したい。

応答形式はHTTPのbodyかheadersか。
- bodyならtext(CharSet,MimeType(JSON,XML)),binary(MimeType)などどの形式か
- headersならどのキーから、どうやって取得するか（ページネーションのLinkキーなどからURL取得は単純な値の取得ではなく複雑）

たとえばOAuthのAPIでは応答がHttpHeaderで取得する形になっている。対してリポジトリ一覧取得の応答はJSON形式。

APIを調査し、全パターン網羅する
DBを設計する

現状のコードでは、APIごとにソースコード上で指定している。

すでに特定できる？

Request.Header.Acceptで特定できるかもしれない
Response.Header.MimeTypeで特定できるかもしれない

HTTPの仕様、GitHubAPIの仕様、requestsライブラリの仕様を調べる必要がある。

APIの実行結果調査が必要か。RESTクライアントでAPI発行し、Headerを見てみるとか。

仮に現時点での結果が出たとしても、どこまで信じるか。どちらを信じるか。

DB値（過去の状態なので今とは違う場合もありうる？）
そのときの値（新機能で間違っているor未修正のバグがありうる？）

ページネーションの有無

Responseの一部。

APIによっては1回のリクエストで全件取得できないものがある。その場合、ページネーションによる複数回のリクエストが必要。たとえばリポジトリ一覧取得の応答にはHttpHeaderのLinkキーがあり、そこから関連URLnextに該当するURLを取得する。

現状のコードでは、APIごとにページネーション処理している。

MimeType

GitHubAPIのHTTP応答がどうなっているのか調査する。MimeTypeが取得できるなら、それを使って返却値の型を自動化できるかもしれない。

またはHTTP要求するときのAcceptにapplication/vnd.github.v3+jsonとするので、応答の型を特定できるかもしれない。

次にすること

GitHubAPIをテキトーに発行してみて応答結果のHttpHeaderを覗いてみる
requestsライブラリの仕様書を見てみる
GitHubAPI仕様書を全体的にざっくり眺めてみる

これで実装とDBのおおまかな形が見えればいいのだが。

所感

次回はGitHubAPIのHttpHeaderを見てみる。

やってみる

アウトプットすべく己を導くためのブログ。その試行錯誤すらたれ流す。

GitHubAPI用DBの不足項目をさがす