RESTfulなAPIを作ろうと思った時の参考になるのがRESTful成熟度の3レベルモデルです。自分たちのAPIがどの立ち位置にあるのかが分かれば、どう改善することでよりRESTfulとして成熟するかが分かるようになるでしょう。
レベル0
まず最初の状態ですが、これは XML-PRC や SOAP が該当するそうです。すなわち、一つのURLと一つのHTTPメソッドで後は送信されるデータで処理内容や処理対象が分かるという方法です。
レベル1
レベル1になると、まずURLが分かれます。しかしHTTPメソッドは変わらず一つです。例えばURLは行う処理によって分かれるものの、HTTPメソッドはすべてPOSTにするといった具合です。PUTやDELETEといったHTTPメソッドが活用されていない状態とも言えます。
レベル2
レベル2になるとURLが分かれているのはもちろん、メソッドも分かれます。CRUD（GET/POST/PUT(PATCH)/DELETE）に分割され、いわゆるRESTfulな状態になります。理想的なAPIとしてAmazon S3を挙げています。
レベル3
ではレベル3とは何でしょうか。それはAPIのレスポンスにハイパーリンク情報を持つことだと言います。例えばAmazon S3のレスポンスにはキー情報は含まれていますが、そのファイルをどういうURLで取得できるのかと言った情報は含まれません。開発者はドキュメントを読み、一定のルールに従ってURLを生成する必要があります。著者であるMartin Fowler氏によれば、Amazon S3はAPIとしては良くできているが、HTMLから学んでいないとのことです。
対してNetflixのAPIレスポンスではリンク情報が含まれており、APIがハイパーメディアとして動作します。これはHATEOASやHALに則った仕組みになります。そうすることで、開発者はどういったURLにアクセスすべきかというロジックを知らなくともAPIを利用できるようになります。
現在、殆どのAPIはレベル2になるでしょう。より利用を広めたり、使いやすいAPIを目指すのであればレベル3を目指すべきです。つまりハイパーメディアの考えを取り入れ、リソースを利用する際に開発者の負担を減らし、より柔軟な連携を実現しましょう。
