Symfony2にREST APIを実装する：正しい方法

REST APIの作成は簡単な作業ではありません。 いいえ、真剣に！ APIを正しく記述したい場合は、よく考え、プラグマティストかAPIマニアかを判断する必要があります。 RESTは、GET、POST、PUT、および削除だけではありません。 実際には、リソース間で相互作用がある場合、リソースを別の場所（ツリー内など）に移動する必要がある場合、または特定のリソース値を取得する場合があります。



この記事には、この目的でSymfony2 、 FOSRestBundle 、 NelmioApiDocBundleおよびPropelを使用してさまざまなAPIサービスを実装することで学んだすべてが含まれています。 たとえば、ユーザーと連携するためのAPIを作成します。

話せますか...？

APIは、クライアントアプリケーションによって使用されます。 彼らはあなたのAPIサービスにアクセスする方法を知っている必要があり、高品質のドキュメントはこれを達成するための良い方法ですが、それについては記事の最後で詳しく説明します。



さらに、クライアントとの通信方法も知っておく必要があります。HTTPプロトコル、つまりAcceptヘッダーはこれに役立ちます。 本質的に、クライアントは受信したいデータ形式のタイプのヘッダーを送信します。



ただし、FOSRestBundleでは、すべてがすでに行われています。 この部分を追跡する必要がありますが、設定でサポートする形式を決定する必要があります。 ほとんどの場合、通常JSONを使用しますが、セマンティクスの問題が発生した場合は、XMLを送信します。 この部分も後で強調表示されます。

何を得る？

HTTP GETメソッドはべき等です。 つまり、このメソッドを使用してデータを何度要求しても、同じデータを受信する必要があります。 変更してはいけません。 GETを使用して、リソース（コレクションまたは個別のリソース）を取得します。 Symfony2では、ルーティングルールの説明は次のようになります。

# src/Acme/DemoBundle/Resources/config/routing.yml acme_demo_user_all: pattern: /users defaults: { _controller: AcmeDemoBundle:User:all, _format: ~ } requirements: _method: GET acme_demo_user_get: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:get, _format: ~ } requirements: _method: GET id: "\d+"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

UserControllerクラスには次のコードが含まれます。

 <?php namespace Acme\DemoBundle\Controller; use Acme\DemoBundle\Model\User; use Acme\DemoBundle\Model\UserQuery; use FOS\RestBundle\Controller\Annotations as Rest; use Symfony\Component\HttpKernel\Exception\NotFoundHttpException; class UserController { /** * @Rest\View */ public function allAction() { $users = UserQuery::create()->find(); return array('users' => $users); } /** * @Rest\View */ public function getAction($id) { $user = UserQuery::create()->findPk($id); if (!$user instanceof User) { throw new NotFoundHttpException('User not found'); } return array('user' => $user); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

get *（）メソッドでパラメーターコンバーターを使用する代わりに、常に自分でオブジェクトを取得する必要があります。 後で説明しますが、今のところは、私を信じてください。本当に良いです。



ステータスコードはクライアントにとって重要です。したがって、ユーザーが存在しない場合は、 NotFoundHttpException例外を使用します。これにより、ステータスコード404の応答が返されます。



View注釈を使用して、ユーザーオブジェクトを目的の形式で表示します。ユーザーはこれをAcceptヘッダーで指定します。 注釈にエイリアス（Rest）を使用することは、後で説明するViewオブジェクトとの競合を回避するのに役立つトリックです。 簡単に言えば、注釈はこのクラスを参照します。 注釈を使用するかどうかにかかわらず、それは好みの問題です。



そして最後に、allAction（）メソッド。 getActionと同じ動作です。ユーザーの選択を取得して返すだけです。



ユーザーオブジェクトには、id、メール、ユーザー名、パスワードの4つのプロパティがあります。 おそらく常識では、APIを介して無料でアクセスするためのパスワードをユーザーに与えることはできません。 オブジェクトをシリアル化するときにこのプロパティを除外する最も簡単な方法は、シリアライザーを設定することです。 YAML形式のセットアップ例：

 # In Propel, the most part of the code is located in base classes # src/Acme/DemoBundle/Resources/config/serializer/Model.om.BaseUser.yml Acme\DemoBundle\Model\om\BaseUser: exclusion_policy: ALL properties: id: expose: true username: expose: true email: expose: true
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

デフォルトでは、オブジェクトのすべてのプロパティを除外することをお勧めします。必要なプロパティは明示的に追加する必要があります。 これにより、大きなオブジェクトの柔軟性が向上します。 これは4つのプロパティではあまり意味がありませんが、それでもこの戦略を守ろうとします。これが最終的にファイアウォールを構成する方法です。



その結果、次のJSON応答を取得します。

 { "user": { "id": 999, "username": "xxxx", "email": "xxxx@example.org" } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

シンプルでしょ？ ただし、おそらくユーザーを作成、変更、または削除する必要があり、これは次の章のトピックになります。

投稿する

ユーザーの作成には、HTTP POSTメソッドの使用が含まれます。 しかし、どのようにデータを受け取りますか？ それらをどのように確認しますか？ そして、新しいオブジェクトをどのように作成しますか？ これらの3つの質問には、複数の回答または戦略があります。



逆シリアル化メカニズムを使用して、シリアル化された入力からフォームオブジェクトを作成できます。 ベンジャミンという名前の男は、 フォーム脱塩装置に取り組んでいます。 この方法は、Serializerコンポーネントを使用する場合とわずかに異なりますが 、より簡単に思えます。



Symfonyのクールなフォームコンポーネントを使用して、一度にすべてを実行します。 新しいユーザーを作成するフォームクラスを作成しましょう。 PropelBundleを使用すると、 propel：form：generateコマンドcommandを使用できます：

 php app/console propel:form:generate @AcmeDemoBundle User
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このコマンドは、次のフォームクラスを作成します。

 <?php namespace Acme\DemoBundle\Form\Type; use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class UserType extends AbstractType { /** * {@inheritdoc} */ public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('username'); $builder->add('email', 'email'); $builder->add('password', 'password'); } /** * {@inheritdoc} */ public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\DemoBundle\Model\User', 'csrf_protection' => false, )); } /** * {@inheritdoc} */ public function getName() { return 'user'; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

私は自分の手で微調整する必要がありました：電子メールとパスワードの種類、そしてCSRF保護もオフにしました。 REST APIでは、ほとんどの場合、OAuthなどのセキュリティレイヤーを使用します。 RESTコンテキストでCSRFを保護しても意味がありません。



ここで、検証ルールを追加する必要があります。 適切なコンポーネントのおかげで、これは簡単になります。 すべての着信データを安全な方法で簡単にチェックできるので、このコンポーネントが本当に気に入っています。



私たちのケースに戻って、YAMLで検証ルールを説明するのに慣れていますが、誰もあなたの選択を制限しません。 以下に例を示します。

 # src/Acme/DemoBundle/Resources/config/validation.yml Acme\DemoBundle\Model\User: getters: username: - NotBlank: email: - NotBlank: - Email: password: - NotBlank:
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

コントローラーでメソッドを書きましょう：

 <?php // ... public function newAction() { return $this->processForm(new User()); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

もう一つのヒント。 フォームの処理には、常に別の方法を使用してください。 それからあなたは自分に感謝します。 processForm（）メソッドは次のようになります。

 // ... private function processForm(User $user) { $statusCode = $user->isNew() ? 201 : 204; $form = $this->createForm(new UserType(), $user); $form->bind($this->getRequest()); if ($form->isValid()) { $user->save(); $response = new Response(); $response->setStatusCode($statusCode); $response->headers->set('Location', $this->generateUrl( 'acme_demo_user_get', array('id' => $user->getId()), true // absolute ) ); return $response; } return View::create($form, 400); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

要するに、フォームを作成し、受信データをそれにバインドし、すべてのデータが有効であれば、ユーザーを保存して応答を返します。 問題が発生した場合は、フォームとともに400コードを返すことができます。 フォームクラスのインスタンスは、エラーメッセージを表示するためにシリアル化されます。 たとえば、次のようなエラーレスポンスが表示される場合があります。

 { "children": { "username": { "errors": [ "This value should not be blank." ] } } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

注：ここで表示されるViewクラスは、アノテーションで使用するものと同じではないため、エイリアスを使用しました。 このクラスの詳細については、FOSRestBundleドキュメントの「View Layer」の章を参照してください。



ここでは、フォームの名前を渡すことも重要です。 通常、顧客は次のようなものを送信します。

 { "user": { "username": "foo", "email": "foo@example.org", "password": "hahaha" } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

curlでこのメソッドを呼び出すことができます：

 curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"user":{"username":"foo", "email": "foo@example.org", "password": "hahaha"}}' http://example.com/users
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

FOSRestBundle設定のbody_listenerパラメーターにtrueを設定してください。 このパラメーターを使用すると、JSON、XMLなどの形式でデータを受信できます。 繰り返しますが、すべてがすぐに使用できます。



前に言ったように、すべてがうまくいけば、ユーザーを保存し（$ user-> Propelで保存）、そして答えを返します。



リソースが作成されたことを示すステータスコード201を送信する必要があります。 このメソッドにはViewアノテーションを使用していないことに注意してください。



しかし、コードをよく見ると、私が奇妙なことをしたことに気付くかもしれません。 実際、リソースを作成するとき、特定の情報、つまりこのリソースへのアクセス方法を返す必要があります。 つまり、URIを返す必要があります。 HTTP仕様には、 Locationヘッダーを使用する必要があると書かれています。 ただし、ユーザーIDなどの情報を取得するために別の要求を行いたいとは思わないでしょう（とにかく残りの情報は既にあります）。 そして、私の主な概念が表示されます：プラグマティストまたはマニアック？



知ってる？ 私はマニアックなアプローチを好み、私は仕様に従い、 Locationヘッダーのみを返します：

 Location: http://example.com/users/999
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

クライアントとしてJavaScriptフレームワークBackbone.jsを使用する場合、正しいAPIをサポートしていないため、その一部を書き換えたくないため、すべてに加えてIdを返します。 実用主義者であることはまだそれほど悪くはありません。



このアクションのルーティングルールを忘れずに追加してください。 リソースの作成はコレクションへのPOST要求なので、新しいルールを追加します。

 acme_demo_user_new: pattern: /users defaults: { _controller: AcmeDemoBundle:User:new, _format: ~ } requirements: _method: POST
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

新しいリソースの作成方法を知っていれば、それを変更するのは非常に簡単です。

PUT vs PATCH、ファイト！

特にHTTP PUTメソッドを使用している場合、リソースを変更すると、リソースが置き換えられます。 また、リソース間の差異を取得して元のリソースにパッチを適用するPATCHメソッドもあります。つまり、 部分更新を実行します。



前に行った作業のおかげで、リソースの変更はかなり簡単に実装できます。 コントローラに新しいメソッドを記述し、新しいルーティングルールを追加する必要があります。 ここでは、ユーザーのオブジェクトを取得するためにパラメーターコンバーターに依存できます。 そのようなユーザーが存在しない場合、パラメーターコンバーターは例外をスローし、この例外はステータスコード404の応答に変換されます。

 <?php // ... public function editAction(User $user) { return $this->processForm($user); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

リソースを変更するということは、そのリソースに関するすべてをすでに知っているため、PUTリクエストでこのリソースのURIのみを返すことができるということです。

 acme_demo_user_edit: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:edit, _format: ~ } requirements: _method: PUT
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そしてそれだけです！ リソースの削除はどうですか？

削除

リソースの削除は非常に簡単です。 ルーティングルールを追加します。

 acme_demo_user_delete: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:remove, _format: ~ } requirements: _method: DELETE
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、短いメソッドを書きます：

 <?php // ... /** * @Rest\View(statusCode=204) */ public function removeAction(User $user) { $user->delete(); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

数十行のコードを書いただけで、CRUD操作を安全に実装する完全に機能するAPIを実装しました。 では、ユーザーインタラクションの追加についてはどうでしょうか？ 例えば、友情？



RESTを介して特定のユーザーのフレンドリストを取得する方法 友人を特定のユーザーに属するユーザーのコレクションと考える必要があります。 この相互作用を実装しましょう。

友情アルゴリズム

最初に、新しいルーティングルールを作成する必要があります。 私たちは友達をユーザーのコレクションと考えているので、リソースから直接取得します。

 acme_demo_user_get_friends: pattern: /users/{id}/friends defaults: { _controller: AcmeDemoBundle:User:getFriends, _format: ~ } requirements: _method: GET
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このアクションは、コントローラーでは次のようになります。

 <?php // ... public function getFriendsAction(User $user) { return array('friends' => $user->getFriends()); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

以上です。 次に、別のユーザーの友達になるプロセスを説明する方法について考えてみましょう。 これをRESTでどのように管理しますか？ 何も作成しないため、友達のコレクションにPOSTを使用することはできません。 両方のユーザーがすでに存在します。 コレクション全体を本当に置き換えたくないため、PUTメソッドを使用することはできません。 それは本当に私たちを困惑させることができます...



ただし、HTTPプロトコル仕様には、問題を解決するLINKメソッドが記述されています。 それは言います：

LINKメソッドは、Request-URIで指定された既存のリソースと他の既存のリソースとの間に1つ以上の関係を確立します。

これがまさに私たちが必要とするものです。 2つのリソースをリンクしたいので、APIサービスを作成するときにリソースを忘れてはなりません。 では、symfony2でこれを行う方法は？



私の方法は、要求リスナーを使用することに基づいています。 クライアントは、リソースのLINK要求を送信し、少なくとも1つのリンクヘッダーを送信します。

 LINK /users/1 Link: <http://example.com/users/2>; rel="friend" Link: <http://example.com/users/3>; rel="friend"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

クエリリスナを使用すると、メソッドでクリーンな入力を取得できるため、非常に便利なオプションです。 最終的に、このメソッドの目的はオブジェクトをリンクすることですが、コントローラーでURIを操作したくありません。 この前にすべての変換を実行する必要があります。



リクエストリスナーはこれらすべてのリンクヘッダーを取得し、それらをSymfony2 RouterMatcherコンポーネントに使用してコントローラーとメソッドの名前を取得します。 また、パラメータを準備します。



つまり、コントローラーを作成し、必要なパラメーターを使用して適切なメソッドを呼び出すために必要なすべての情報が含まれています。 この例では、UserControllerのgetUser（）メソッドが各Linkヘッダーに対して呼び出されます。 これが、パラメーターコンバーターを使用しなかった理由です。これにより、引数の値としてidを使用できるようになり、そのためリソースを取得できました。 私はいくつかの仮定をしました：

• ユーザーが存在しない場合、例外が返されます。
• View注釈を使用したため、戻り値として配列を取得します。

リソースオブジェクトを取得したら、それらを要求属性として配置し、リスナーの場合、作業は完了します。 コードは次のとおりです。

 <?php namespace Acme\DemoBundle\EventListener; use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface; use Symfony\Component\Routing\Matcher\UrlMatcherInterface; use Symfony\Component\HttpFoundation\Request; class LinkRequestListener { /** * @var ControllerResolverInterface */ private $resolver; private $urlMatcher; /** * @param ControllerResolverInterface $controllerResolver The 'controller_resolver' service * @param UrlMatcherInterface $urlMatcher The 'router' service */ public function __construct(ControllerResolverInterface $controllerResolver, UrlMatcherInterface $urlMatcher) { $this->resolver = $controllerResolver; $this->urlMatcher = $urlMatcher; } public function onKernelRequest(GetResponseEvent $event) { if (!$event->getRequest()->headers->has('link')) { return; } $links = array(); $header = $event->getRequest()->headers->get('link'); /* *   ,     *     . * *         Link   * http://tools.ietf.org/html/rfc2068#section-19.6.2.4 */ while (preg_match('/^((?:[^"]|"[^"]*")*?),/', $header, $matches)) { $header = trim(substr($header, strlen($matches[0]))); $links[] = $matches[1]; } if ($header) { $links[] = $header; } $requestMethod = $this->urlMatcher->getContext()->getMethod(); //    GET    //     ,      (LINK/UNLINK) $this->urlMatcher->getContext()->setMethod('GET'); //           $stubRequest = new Request(); foreach ($links as $idx => $link) { $linkParams = explode(';', trim($link)); $resource = array_shift($linkParams); $resource = preg_replace('/<|>/', '', $resource); try { $route = $this->urlMatcher->match($resource); } catch (\Exception $e) { //        //     Link continue; } $stubRequest->attributes->replace($route); if (false === $controller = $this->resolver->getController($stubRequest)) { continue; } $arguments = $this->resolver->getArguments($stubRequest, $controller); try { $result = call_user_func_array($controller, $arguments); //       if (!is_array($result)) { continue; } //     $links[$idx] = current($result); } catch (\Exception $e) { continue; } } $event->getRequest()->attributes->set('link', $links); $this->urlMatcher->getContext()->setMethod($requestMethod); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これで、ルーティングルールを作成できます。

 acme_demo_user_link: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:link, _format: ~ } requirements: _method: LINK
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、アクションのコードは次のようになります。

 <?php // ... /** * @Rest\View(statusCode=204) */ public function linkAction(User $user, Request $request) { if (!$request->attributes->has('link')) { throw new HttpException(400); } foreach ($request->headers->get('Link') as $u) { if (!$u instanceof User) { throw new NotFoundHttpException('Invalid resource'); } if ($user->hasFriend($u)) { throw new HttpException(409, 'Users are already friends'); } $user->addFriend($u); } $user->save(); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ユーザーがすでに友人である場合、ステータスコード409の応答を受け取ります。これは、競合が発生したことを意味します。 要求にリンクヘッダーが含まれていない場合、これは不適切な要求（400）です。



友人から削除する場合も同様です。 ここでのみ、 UNLINKメソッドを使用します。



そして最後に。 PATCHメソッドについては説明しませんでした。 つまり、この方法のシナリオはどうなるのでしょうか？ 答えは、部分的な更新、または安全でない、信頼できない、またはべき等でないメソッドです。 非標準のメソッドがあり、どのメソッドを使用するかわからない場合は、PATCHが最適です。



ユーザーがサードパーティのクライアントを介してメールを変更できると仮定します。 このクライアントは2段階のプロセスを使用します。 ユーザーは自分の電子メールアドレスを変更する許可を要求し、リンクが記載された電子メールを受信し、それをクリックして、変更の許可を取得します。 最初のステップをスキップして、2番目に焦点を合わせます。 ユーザーは新しいメールをクライアントに送信し、クライアントはAPIメソッドを呼び出す必要があります。 クライアントがリソースを受け取り、それを置き換えるか、賢明でPATCHメソッドを提供します。

PATCHの世界に課す

まず、新しいルーティングルールを定義します。

 acme_demo_user_patch: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:patch, _format: ~ } requirements: _method: PATCH
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、コントローラに安全なpatchAction（）メソッドを書くために、想像力を有効にします。 ユースケースを見てみましょう。 クライアントは、リソースの1つ以上の値を送信できます。 すべての優れたルービストが行うように、ホワイトリストに依存して大量の割り当てを防ぐことは素晴らしいことです...



入力パラメータをフィルタリングしましょう：

 <?php $parameters = array(); foreach ($request->request->all() as $k => $v) { //   if (in_array($k, array('email'))) { $parameters[$k] = $v; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

着信パラメーターをフィルター処理するとすぐに、必要なパラメーターを正確に取得しました。 何も受信しなかった場合、これは不適切なリクエストであり、ステータスコード400のレスポンスを返す必要があります。



すべてが順調であれば、新しい値をリソースに割り当てることができます。 ああ待って...いいえ！ 最初にエンティティを確認し、すべてのデータが有効な場合にのみ保存する必要があります。



このアクションのコードは次のようになります。

 <?php // .... public function patchAction(User $user, Request $request) { $parameters = array(); foreach ($request->request->all() as $k => $v) { // whitelist if (in_array($k, array('email'))) { $parameters[$k] = $v; } } if (0 === count($parameters)) { return View::create( array('errors' => array('Invalid parameters.')), 400 ); } $user->fromArray($parameters); $errors = $this->get('validator')->validate($user); if (0 < count($errors)) { return View::create(array('errors' => $errors), 400); } $user->save(); $response = new Response(); $response->setStatusCode(204); $response->headers->set('Location', $this->generateUrl( 'acme_demo_user_get', array('id' => $user->getId()), true // absolute ) ); return $response; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

コードはとても簡単ですよね？ いつものように、リソースを作成または更新するときは、2xxステータスコードとLocationヘッダーを含む応答を送信する必要があります。 ここにはコンテンツがなく、何も作成していないため、コード204を送信します。



そして今、計画は何ですか？ GET、POST、PUT、DELETE、PATCH、LINK 、およびUNLINKメソッドをすでに使用しています 。 ユーザーを作成、受信、変更、削除、さらには部分的に更新することもできます。 すべてのユーザーのリストを取得し、ユーザー間の友情を確立できます。 ユーザーデータを変更する必要がある場合、 PATCHメソッドを安全に使用できることがわかっています。



実際、 Richardson Maturityモデルに関しては 、第2レベルのみを取り上げました。 それでは、 HATEOASを見て、第3レベルのロックを解除しましょう！

嫌いな人は？

HATEOASは憎しみとは何の関係もありませんが、あなたが実際的なプログラマーであると考えるなら、このアプローチを嫌うことができます。 この頭字語は、Hypermedia As The Engine Of Application Stateの略です。 私にとって、これはセマンティクスをAPIサービスに追加することと見なされます。



この記事の前半で、クライアントとAPIの間で情報を交換するために使用される形式について説明しました。 HATEOASの原則に従うことを決めた場合、JSONは最良の選択肢ではありませんが、 この問題の解決策を提供する人もいます 。



ユーザーの表現をXMLに変換します。

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> </user>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これは、クライアントがXMLを要求した場合のgetメソッドの出力です。 HATEOASからは何もありません。 最初のステップは、リンクを追加することです。

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> </user>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

それは簡単で、データを受け取ったユーザーを参照するリンクを追加しただけです。 ただし、ユーザーコレクションがページ分割されている場合は、次を取得できます。

 <users> <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> <link href="http://example.com/users/999/friends" rel="friends" /> </user> <user> <id>123</id> <username>foobar</username> <email>foobar@example.org</email> <link href="http://example.com/users/123" rel="self" /> <link href="http://example.com/users/123/friends" rel="friends" /> </user> <link href="http://example.com/users?page=1" rel="prev" /> <link href="http://example.com/users?page=2" rel="self" /> <link href="http://example.com/users?page=3" rel="next" /> </users>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これで、クライアントはコレクションを表示する方法、ページをナビゲートする方法、ユーザーや友人を取得する方法を知っています。



次のステップでは、質問への回答としてメディアタイプを追加します。リソースとは何ですか？それには何が含まれますか、そのようなリソースを作成するには何が必要ですか？



このパートでは、独自のコンテンツタイプを紹介します。

 Content-Type: application/vnd.yourname.something+xml
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ユーザーは、次のタイプのコンテンツを参照するようになりました：application / vnd.acme.user + xml。

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> <link rel="friends" type="application/vnd.acme.user+xml" href="http://example.com/users/999/friends" /> </user>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

最後になりましたが、3つの異なる方法でAPIサービスにバージョン管理を追加できます。簡単な方法は、URIにバージョン番号を追加することです。

 /api/v1/users
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

別の方法は、新しいコンテンツタイプを宣言することです。

 application/vnd.acme.user-v1+xml
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

または、Acceptヘッダーでバージョンポインターを使用できます。この場合、コンテンツのタイプを変更する必要はありません。

 application/vnd.acme.user+xml;v=1
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

使用する方法を選択します。最初の方法が最も簡単ですが、他の2つよりもRESTfulでもありません。確かに、他の2つにはよりスマートなクライアントが必要です。

テスト中

正直に言うと、APIサービスを顧客に提供することにした場合、このセクションが最も重要です。RESTイデオロギーに完全に従うかどうかを選択できますが、APIサービスは完全に機能する必要があります。つまり、十分にテストされている必要があります。



APIサービスを機能テストでテストしたいので、システムをブラックボックスと見なします。Symfony2には、テストクラスでAPIメソッドを直接呼び出すことができる優れたクライアントが含まれています。

 $client = static::createClient(); $crawler = $client->request('GET', '/users'); $response = $this->client->getResponse(); $this->assertJsonResponse($response, 200);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

assertJsonResponse（）メソッドを実装したWebTestCaseクラスを使用します。

 <?php // ... protected function assertJsonResponse($response, $statusCode = 200) { $this->assertEquals( $statusCode, $response->getStatusCode(), $response->getContent() ); $this->assertTrue( $response->headers->contains('Content-Type', 'application/json'), $response->headers ); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これは、API呼び出しの直後に実行される最初の検証手順です。すべてがうまくいけば、受け取ったデータに既に関連している他のチェックを実行します。



APIサービスのテストを作成するときは、思いついたことを確認してください。不正な要求を確認し、可能性のあるステータスコードごとに少なくとも1つのメソッドとクライアントへの正しいメッセージをテストに含めることを忘れないでください。コード500は400と同じ意味ではありません。

ドキュメント

適切なAPIドキュメントを作成することは、クライアントがアクセスできる唯一のものであるため、非常に重要なパラメーターです。すべてのコードを提供しませんか？



HATEOASアプローチを使用する場合、APIにはすでにドキュメントが含まれているため、顧客自身が利用可能なすべてのオプションについて学習するため、自分で作成する必要はありません。



しかし、HATEOAS APIの実装は非常に困難であり、現時点ではあまり一般的ではありません。 APIサービスがRichardsonモデルの第2レベルに従う場合、これはすでに適切ですが、すべてのドキュメントを自分で作成する必要があります。



しかし、NelmioApiDocBundleが助けになります。このバンドルはNelmioで書いたAPIサービスのドキュメントを自動的に生成します。コードのイントロスペクションに基づいて、バンドルは多くの異なる情報を受け取り、適切に設計されたページに表示します。









これで、素晴らしいAPIサービスを構築するためのすべてが手に入りました。

便利なリンク

• RFC 2616-セクション10-ステータスコードの説明。
• RFC 2068-セクション19.6-追加機能
• RFC 5988-Webリンク。

翻訳の著者から：元の記事の著者は、さらに更新する予定です。また、翻訳でエラー、不正確、または見苦しいフレーズを見つけた場合は、個人メッセージで報告してください。記事の量と睡眠不足を考えると、おそらく不正確さがあります。