2019.04.08

【MuleSoftクイックスタートガイド】 最初のAPIの設計

  • このエントリーをはてなブックマークに追加
  • follow us in feedly
gettyimages (10430)

※この記事は、下記MuleSoftの記事を、許可を得ていち早く翻訳したものです。
https://developer.mulesoft.com/guides/quick-start/designing-your-first-api

MuleSoftクイックスタートガイドへようこそ。 このガイドはAPIのライフサイクルをたどりながら、Mule Platformの異なる領域を紹介する4部構成のガイドです。各ガイドで学習する内容は次のとおりです。

Guid# 内容
1 - 最初のAPIの設計(このガイド) Anypoint Design Centerを使用してAPI仕様を作成し、Anypoint Exchangeに公開します。
2 - 最初のMuleアプリケーションの開発 Anypoint Studioを使用してMySQLデータベースからデータを取得するMuleアプリケーションを開発します。
3 - 最初のAPIのデプロイと管理 ローカルで作成したアプリケーションをCloudHubにデプロイし、ポリシーを適用します。
4 - 最初のSaaSアプリケーションとの接続 Flow DesignerでAPIを再利用してSalesforceとSlackを統合します。

各ガイドで作成する内容はAnypoint Exchangeに公開されています。すでに設計および構築されているAPIのデプロイ方法について学びたいだけの場合はガイド3に進んでください。ガイド3では公開されているAPI仕様、アプリケーションをダウンロードしてインポートする方法が紹介されています。

概要

ガイド1では、API仕様とMuleSoftのAnypoint Platformを活用してデータ統合アプリケーションを構築する方法について学びます。

  • API Designerとは?API Designer使用してAPI仕様を作成する方法は?
  • API仕様を効率よく設計するために考慮すべき事項は何か?
  • APIコンソールでAPI仕様に対してどのようにテスト、検証を行うか?

API仕様を最初に設計するのはなぜか

MuleでHTTPベースのデータ統合アプリケーションを構築するにあたり、最初に行うべきことはAPI仕様を書くことです。仕様を作成するのに時間がかけることにはいくつかの重要な利点があります。

  • デプロイされたAPIを利用、再利用するためのドキュメントを提供します。
  • APIのステークホルダー/コンシューマーがアプリケーションを構築される前に受け入れテストを実行できます。
  • API仕様を使用すると開発時間を短縮するために実装に成果物とメタデータを事前に取り込むことができます。

準備

  1. まだ行っていない場合は、必ず30日間の無料Anypoint Platformアカウントにサインアップしてください。 API DesignerでAPI仕様を作成しFlow DesignerでMuleアプリケーションを作成するにはAnypoint Platformのアカウントが必要となります。
  2. 製品のデータベースのExcelをダウンロードしてください。 次の演習では、APIを構築する際の参照として使用するためにこのデータを使用します。
    congo.xlsx

API仕様とは

API仕様は、人間とコンピュータシステムの両方が容易に理解できる強力な規約です。APIドキュメント(readmeなど)とAPI定義(WSDLファイルなど)の両方が組み合わされているため利用しやすいです。また、この設計方法は実装側の理解を単純化するためプロジェクトの完成が早くなります。それでは、ここで使用する言語「RAML」でAPI仕様の設計を開始しましょう。

OASやSwaggerのインポートもサポートされておりRAMLに変換することが可能です。RAMLはMuleSoftのAPI DesignerのネイティブAPI仕様言語です。RAMLの詳細については、RAML.orgを参照してください。

eコマースの例を活用する

eコマースストア用のAPIを構築していると仮定すると、まず商品APIを構築することから始めることができます。 商品APIの要件の1つは、ストア内の特定の商品に関する詳細を提供することです。 HTTP GETメソッドをサポートする /products/{productId}エンドポイントを作成し、何をリクエストし、何をレスポンスするかについての詳細を設計していきます。

Design CenterでAPI仕様を作成する

Anypoint PlatformのDesign Centerに入ることから始めましょう。

  1. Create」ボタン→「API Specification」を選択します。
  2. 「Project Name」にAPI仕様の名前を入力します。
  3. 「Start with API Designer」を選択します。
  4. 「Create」ボタンを押下します。

alt

これでAPI Designerで新しいAPI仕様のひな型が作成されました。

  1. 初期セットされている入力文字を削除します。
  2. 以下のRAMLをコピー&ペーストしてください。(あるいは公開されたExchangeよりRAMLをダウンロードすることも可能です。実際の作業ではこのようにしてほかのチームが作成、公開したRAMLを使用することで時間の節約が可能となります。)
title: DevRel-Quick Start Products API
version: v1.0

securitySchemes:
  basic:
    description: |
      This API supports Basic Authentication.
    type: Basic Authentication
         が

securedBy: [basic]

types:
  product:
    properties:
      identifier?: string
      identifiers: IdentifierMap
      brand: string
      model: string
      rating: number
      description?: string
      pictures: string[]
      price: price
  
  price:
    properties:
      amount: amount
      salesUnit: salesUnit
      
  amount:
    properties:
      currency: string
      currencyValue: number
      name : string
  
  salesUnit:
    properties:
      code: string
      name: string
  
  Identifier:
    type: string
    pattern: ^[0-9A-Za-z-]+
    minLength: 3
    maxLength: 36

  IdentifierMap:
    type: array
    items:
      type: object
      properties:
        /[0-9A-Z-]+/:
          type: Identifier

/products:
  /{productId}:
      uriParameters:
        productId: string
      get:
        responses: 
          200:
            body:
              application/json:
                type: product
                example: |
                  {
                    "brand": "Anypoint",
                    "identifier": "eb8c8ca7-3c42-4489-a820-3aa138430b75",
                    "identifiers": [{
                      "SKU": "UGG-BB-PUR-06"
                    }],
                    "model": "Smart Slim Micro Stripe Shirt",
                    "rating": 5,
                    "description": "Shirt by ASOS Tall. Stripe woven fabric. Added stretch for comfort. Spread collar. Button placket. Slim fit - cut close to the body. Machine wash. 98% Cotton, 2% Elastane. Our model wears a size Medium Long and is 193cm/6'4\" tall",
                    "pictures": [
                      "https://launderkart.com/wp-content/uploads/2016/07/Shirt.jpg",
                      "https://cdni.llbean.net/is/image/wim/251423_47_41?wid=428&hei=494"
                    ],
                    "price": {
                      "amount": {
                        "currency": "USD",
                        "currencyValue": 34.90,
                        "name": "Amount"
                      },
                        "salesUnit": {
                        "code": "EA",
                        "name": "Each"
                      }
                    }
                  }
          404:
            body: 
              application/json:
                properties:
                  message: string
                example: |
                  {
                    "message" : "Product not found"
                  }
```
RAML 1.0

仕様の理解

上記のAPI仕様を見てください。最初にTop-Levelの定義としてAPIの概要が定義されています。 つづいて、サポートされている認証方法(basic認証)が定義され、それをsecureByパラメーターを使用してすべてのエンドポイントおよびメソッドにグローバルに割り当てます。 さらに、API仕様はProductのdata-typeを定義しています。data-typeにはパラーメータや種類などの定義が含まれています。以後、identifiersMap, price, sales unitなどのdata-typeが同様に定義されています。これらのdata-typeはこのRAML定義全体で利用可能な定義となります。 次にAPI仕様はエンドポイント(/products/{productId})を定義しています。エンドポイントでは要求側に期待するもの(アイテムID、コンテンツタイプ、および列挙されたクエリパラメータ)、および、その応答の内容が説明されています。処理が成功するとステータスコード200の応答の例としてJSON本文に指定されたデータ型が出力されます。 またエラーのパターンとしてステータスコード404(Not Found)の例外エラーも記述されています。

Mocking serviceを使用してAPIをテストする

API仕様をAPI開発のプロトタイプとするためにテストするときが来ました。 まず、右側のペインでスイッチを反転して、API Designerの組み込みMock Serviceをオンにします。

alt

RAML仕様の先頭にbaseUriという新しいパラメータが追加されます。この公開URLはこのAPIに接続するためのベースのパスとなります。すべてのエンドポイントはこのベースのパスに追加されることとなります。

※ Mocking serviceはテスト用であり、実運用では使用できません。

Mocking serviceにリクエストを送信する

右側のペインには、リクエストを送信して仕様に対する応答を確認するためのAPIコンソールが含まれています。 1. 右側のペインのAPI endpointsの/products/{productId}エンドポイントのGETリンクをクリックする。  

  1. 青い「Try it」ボタンを押下する。 
  2. Authorization methodタブのusernameとpasswordにそれぞれMuleSoftのユーザID、パスワードを入力する。  
  3. parametersタブのproductidに任意の値(2など)を入力する。  
  4. 「Send」ボタンを押下する。  
  5. Mocking serviceの結果が下部に表示されることを確認してください。   

Mocking serviceは正常な応答(ステータスコード:200)をexampleで指定した内容で返すはずです。このテストはWebブラウザなどの別のWebクライアントやcurl(外部リンク)などを使用しても同様のテストが可能です。

curl -X GET https://{{yourMockingServiceUrl}}/products/1

このMocking serviceのURLは他の関係者と共有することができ、設計段階でのテストに利用できます。

再利用できるように仕様を公開する

このAPI仕様は間違いなく機能するので次のフェーズとしてこのAPI仕様を公開しましょう。API仕様を公開することによりあなたとAnypoint Exchangeで十分な権限を持っている人なら誰でもこのAPI仕様を参照、使用することができるようになります。公開にあたり、最初にBaseUriパラメータを削除する必要があります。以下の画像のようにMocking serviceを停止してください。 alt

公開手順は以下となります。

  1. 公開アイコンをクリックします。  
  2. 「Publish to Exchange」を選択します。    
  3. 初期値そのままで、「Publish」ボタンを押下します。   

これであなたが作成するアプリケーションの設計はより多くの人が参照し、利用できる状況になりました。 private Exchangeで「Quickstart-store」(またはプロジェクトの前のステップで選択した名前)を検索できるはずです。API仕様が正しいことを確認するには、既にPublic Exchangeで公開しているものと比較します。

次のステップ

これでこのガイドは完了です!Anypoint PlatformでAPI仕様を構築、共有、およびテストしました。次のステップではこのAPI仕様を使用して、Muleアプリケーションを構築しデプロイします。

26 件
     
  • banner
  • banner

関連する記事