Skip to main content
Bring your team and maximize your impact at Dreamforce. Register three or more to unlock $999 passes.

API をパブリッシュして共有する

学習の目的

この単元を完了すると、次のことができるようになります。

  • API を Anypoint Exchange にパブリッシュする利点を説明する。
  • 表示設定が API にアクセスできるユーザーにどのように影響するかを説明する。
  • 開発者が API を発見、テスト、採用するのに API ポータルがどのように役立つかを確認する。

API をパブリッシュする

API 設計は、ほんの始まりにすぎません。作業内容を有用なものにするには、ほかの人が見つけ、理解し、再利用する必要があります。だからこそ、API チームはほかの人が見つけて確認できる一元化されたプラットフォームに API をパブリッシュするのです。

Anypoint Exchange のようなツールは、静的な API 定義を文書化された検出可能かつ共有可能なアセットに変えるのに役立ちます。API が見つけやすくて理解しやすいと、チームは再開発に費やす時間を短縮し、価値の提供にかける時間を増やすことができます。

API ライブラリにいる 2 人の人物。1 人は「テンプレート」というラベルが付いた棚の本を読み、もう 1 人は「API」というラベルの付いた棚に本を加えている。

Anypoint Exchange にパブリッシュする主な利点

  • 再利用の高速化: チームは、作業内容を複製するのではなく、その内容に基づいて構築することができます。
  • コラボレーションの向上: 関係者は、バックエンド開発の前であっても、確認してフィードバックを提供することができます。
  • 明確な所有権: パブリッシュされた API にはメタデータとバージョン管理が含まれているため、ほかのユーザーがそのアセットの管理者を把握できます。
  • 可視性の向上: API は表示設定に応じて、内部チームまたは世界で使用できる検索可能なカタログの一部になります。

Mule United Airport が API をパブリッシュする

Mule United Airport (MUA) チームは、提携航空会社がスケジュール済みのフライトを検索するのに役立つ API を設計しています。チームが API をモックしてテストしたら、仕様を Anypoint Exchange にパブリッシュします。それにより、その仕様を組織のほかのメンバーが使用できるようになります。結果:

  • 提携航空会社は、API のエンドポイントと想定される応答を確認できます。
  • フロントエンド開発者は、データ例を使用して UI を作成できます。
  • サポートチームは、ドキュメントがある場所と問い合わせ先がわかります。

パブリッシュしなければ、そのようなコラボレーションは制限されるか、下手すると、メールか共有ドライブに散在している古くなったドキュメントに基づいて行われてしまいます。

API チームが Anypoint Exchange にパブリッシュする方法を学ぶ

API がより広範に利用できる準備が整うと、チームは通常 MuleSoft のブラウザーベースの IDE である Anypoint Code Builder のようなツールを使用して Anypoint Exchange にパブリッシュします。パブリッシュすることで、API の記述、バージョン管理、共有の方法をチーム間で標準化できるようになります。

以下は、そのプロセスの概要です。

API プロジェクトを準備する

チームは、API 仕様 (多くの場合 OAS) と関連ファイルを Anypoint Code Builder のプロジェクトワークスペース内に整理します。

パブリッシュフローを起動する

IDE には、アセットを Anypoint Exchange にパブリッシュするためのガイド付きプロセスが用意されています。これは、チームが適切に文書化された検出可能な API を作成するのに役立ちます。

メタデータを定義する

API を説明するための重要な情報が追加されます。これには、次の情報が含まれることがあります。

  • アセットバージョン: アセットのリリースバージョン (例: 1.0.0) を識別します。
  • API バージョン: インターフェースまたはコントラクトのバージョンを示します。
  • ビジネスグループ: API の所有者と管理者を示します。
  • 名前と説明: 明確なタイトルと API の実行内容の概要 (例: 「Returns scheduled on American flights from Mule United Airport based on origin, destination, and date」(出発地、目的地、日付に基づく Mule United Airport 発の American 航空便でスケジュールされている復路便)) を示します。

検出性を高めるためにタグを追加する

flights、partner-access、または internal-api のようなタグは、チームが Anypoint Exchange で適切な API を見つけ、そのユースケースを一目で理解するのに役立ちます。

パブリッシュして共有する

メタデータが確認されたら、チームはアセットをパブリッシュします。Anypoint Exchange によって仕様が検証され、その表示設定に基づいて自動的に API ポータルが作成されます。このポータルには次の要素が含まれます。

  • API 参照ドキュメント
  • エンドポイントを試行するためのインタラクティブなコンソール
  • 追加リソースの連絡先情報とリンク

表示の設定方法に応じて、API は次の状態になります。

  • 非公開 (ビジネスグループ内でのみアクセス可能)
  • 公開 (外部開発者が利用可能)
  • 特定のチームまたはパートナーと共有

こうした制御によって、API を見つけやすく、かつ再利用しやすくしながら安全に維持します。

API に誰がアクセスできるかを制御する: 非公開設定と公開設定の比較

API のパブリッシュは重要な最初のステップですが、誰が API を見つけて使用できるかを決めることも重要です。

Anypoint Exchange では、表示を制御できます。内部 API をセキュアに維持し、一般に公開されている API には簡単にアクセスできるようにすることが可能です。部門間でインテグレーションを共有する場合でも、サービスをパートナーに公開する場合でも、適切な表示設定は API が適切な使用者にリーチするのに役立ちます。

「非公開」というラベルが付いた鍵のかかったドアには、キーパッドでのみアクセスできる。「公開」というラベルが付いたドアは開いている。

非公開 API

非公開 API は、Anypoint Platform 内の自分の組織または特定のビジネスグループのユーザーにのみ表示されます。次の場合に適しています。

  • 社内のツールとサービス
  • 開発またはテストフェーズの初期段階の API
  • 分離された環境で作業するチーム (開発や QA など)

MUA では、運用チームが内部スケジュールの確認、乗務員の運用計画の管理、セキュリティシステムの監視を行うために非公開 API を使用する場合があります。こうしたサービスは、バックグラウンドで動作し、認証されたユーザーのみがアクセスできるようにする必要があります。

公開 API

公開 API は、リンクを知っていれば、組織外の開発者を含む誰でもアクセスできます。次の場合に適しています。

  • パートナーインテグレーション
  • 教育または政府のオープンデータサービス
  • 採用を促進、奨励する必要のある API

たとえば、American Flights API は提携航空会社向けです。MUA は公開 API を使用しているため、外部開発者は追加のオンボーディングを必要とせずに API ポータルを見つけ、エンドポイントをテストし、インテグレーションを開始することができます。

Anypoint Exchange の表示設定のしくみを知る

API が Anypoint Exchange でパブリッシュされたら、アクセスできるユーザーを設定できます。引き続き、完全に制御できます。

デフォルトでは、パブリッシュされた API は非公開で、所有者のみがそのアセットを表示してアクセスできます。API を誰でも見つけることができるようにするには、表示設定を「公開」に変更します。これにより、URL を知っていれば誰でも API ポータルとドキュメントを表示できるようになります。

この設定はいつでも調整できるため、API の用途が内部テストから外部とのコラボレーションへと変化する際にも容易にアクセスを管理できるようになります。

変更はすぐ有効になり、いつでも更新できます。

Note

公開 API であっても、無制限にアクセスが許可されるわけではありません。クライアント ID 適用や Oauth のような認証ポリシーを使用して実際のランタイムアクセスを保護することもできます。このトピックについては、次のバッジで学びます。

API ポータルを作成してカスタマイズする

API がパブリッシュされ、表示の設定が終わると、次のステップはほかのユーザーがその API を見つけてうまく利用できるようにすることです。

API ポータルは、Anypoint Exchange に組み込まれた Web ベース環境です。API へのわかりやすい入口として機能し、開発者、パートナー、またはチームが自信を持って API を理解し、テストし、採用するために必要なすべてのものを提供します。

優れたポータルは、技術仕様を親しみやすく有益なリソースへと変えてくれます。それは API の第一印象であり、多くの場合、混乱を招くか、インテグレーションが成功するかの分かれ道となります。

API ポータルの機能

Anypoint Exchange 内の API ポータルは、以下の点でコンシューマーに役立ちます。

  • 明確なドキュメントによって API の実行内容を理解できる
  • サンプルユースケースと概要を確認できる
  • 実際の例を使用してエンドポイントを試せる
  • 組み込みコンソールから直接 API を操作できる

このような環境では導入の障壁が低くなり、開発者はパブリッシュチームからの追加のサポートを必要とせずに、すばやく使用を開始できます。

ポータルに含める要素

利用者のニーズに合わせて API ポータルをカスタマイズします。次のことを考慮します。

  • 歓迎テキスト: API の目的と対象者を明確に説明する短い概要を含めます。例:「The American Flights API provides flight availability for MUA’s airline partners. Use it to search by origin, destination, and date.」(American Flights API は MUA の提携航空会社に空席情報を提供します。出発地、目的地、日付で検索できます。)
  • 例とウォークスルー: 開発者が推測しなくてもすむように、一般的な要求の形式を設定する方法と要求を解釈する方法を示します。
  • ブランド要素: ポータルに専門的で信頼できる印象を与えることができるように、組織のロゴ、配色、画像を追加します。
  • サポート情報: どこでサポートを得られるかをユーザーに知らせます (メールアドレス、Slack チャンネル、またはドキュメントへのリンク)。

その API に初めて触れる開発者の視点に立って考えてみてください。スムーズに使い始めるには、何があれば役立つでしょうか?

API のカスタマイズが重要な理由

入念に構築された API ポータルでは、次のようなことを実現できます。

  • よくある質問に前もって回答することで、サポートチケットが減少する。
  • 明確な使用指針によって採用が加速化する。
  • 一貫性のあるブランド設定と透明性の高いコミュニケーションで信頼を築く。
  • API チームに連絡しやすくなり、フィードバックが促される。

MUA では、American Flights API をパブリッシュする開発者はフライトの一般的なクエリの実際の例を追加し、エンドポイントの応答に空港コードをタグ付けします。これにより、提携航空会社のインテグレーションが簡素化され、メールのやり取りを重ねる必要がなくなります。

シンプルに開始して、反復する

完璧さを求めすぎないでください。基本的なコンテンツで API ポータルをパブリッシュし、徐々に改善していくことができます。実際、開発者からのフィードバックに基づき反復的に改善を重ねることは、ポータルを関連性が高く有益なものに保つための最良の方法の 1 つです。

API に命を吹き込む

API をパブリッシュすることは、再利用可能かつ検出可能な製品としての始まりです。API を Anypoint Exchange に追加し、適切な表示を設定し、ポータル環境をカスタマイズしたら、作成された API をほかのユーザーが簡単に見つけ、理解し、採用できるようになります。さまざまな点を考慮してパブリッシュすれば、API を内部チームと外部パートナー双方にとって真に価値あるものにすることができます。

Salesforce ヘルプで Trailhead のフィードバックを共有してください。

Trailhead についての感想をお聞かせください。[Salesforce ヘルプ] サイトから新しいフィードバックフォームにいつでもアクセスできるようになりました。

詳細はこちら フィードバックの共有に進む