第17章 要約: デベロッパーポータルのビギナーからエキスパートに

API 開発のベストプラクティスの調査からは、適切な構成のデベロッパーポータルと優れたドキュメントが、確実に API を利用してもらうための鍵であることが分かっています。デベロッパーポータルは、単なるドキュメントのソースではありません。開発者とのやり取りを管理するためのメインハブでもあり、また開発者はデベロッパーポータルを通じて API キーにセキュアにアクセスすることができます。

17.1. 目的

本チュートリアルでは、デベロッパーポータルを稼動状態にして API をプロモートし、開発者がサインアップしてアカウントを作成し、API キーにアクセスするのを許可する方法について説明します。

17.2. デベロッパーポータルの設定

17.2.1. ポータルのコンセプトのプランニング

初期の段階から、デベロッパーポータルの概念をプランニングすることを推奨します。プランで考慮すべき最も重要な要素には以下が含まれます。

  • サイトマップ: ポータル構造の骨格
  • トップメニューバー: すべてのページで繰り返し表示されるナビゲーション
  • サイドメニューバー: 各セクション内の個々のページへのアクセス用
  • ページレイアウトのガイドライン: ポータルの外観と操作感に一貫性を持たせる

17.2.2. 編集環境の設定

編集環境に最適なセットアップは、以下のとおりです。

  • 管理者クレデンシャルでログインする yourcompany-admin.3scale.net/p/admin/cms を示すタブ。ポータルのデベロッパーポータルにアクセスすることができます。
  • ポータルの公開ビューである yourcompany.3scale.net をポイントする別のタブ (Site リンクでこれにアクセスする場合、アクセスコードを心配する必要はありません)。

管理パネルでは、左側のサイドバーにデベロッパーポータルの要素がすべて表示されます。

Developer Portal home page

17.2.3. ページレイアウトテンプレートの定義

一般的な考え方としては、ポータルのさまざまなページスタイルごとに、個別のレイアウトを定義します。設定開始時には、「main layout」という 1 つの標準レイアウトがあります。このレイアウトはすべてのシステム生成ページで使用されるので、デベロッパーポータルの使用に十分に慣れるまでは、何も変更すべきではありません。通常、ご自分のポータルのホームページには固有のスタイルが必要になります。

  1. main layout テンプレートが、カスタマイズの出発点となります。新しいレイアウトを作成し、main layout のコンテンツをコピーしてそこに貼り付けます。

    Developer Portal Layouts
  2. 「home layout」から以下の行を削除して、サイドバーメニューを削除します。

    {% include 'submenu'%}
    Developer Portal Layouts edit

17.2.4. ページ階層の作成

  1. サイトマップのルートレベルから始め、各トップメニュー項目に対して新しいセクションを追加します (右側の「new」ボタンを展開してセクションを追加します)。タイトル、親セクション、およびパスを割り当てます。

    Developer Portal Sitemap
  2. セクションの追加と同様に、ページを追加します。URL パスの構造に一貫性を持たせるため、目的のセクションを選択します。次に、ページで使用するレイアウトを選択します。ページコンテンツが完成したら、「Create Page」をクリックします。多くのコンテンツを作成する場合は、Textile や Markdown などのマークアップ言語の使用が望ましい可能性があります (高度なページ設定で選択できます)。

    Developer Portal Sitemap new page
  3. ドラフトのプレビューを表示し、満足のできる公開バージョンができるまで、ページコンテンツを改良します。

    Developer Portal publish page
  4. セクションのすべてのページに対して手順を繰り返します。
  5. 次に、サイトのすべてのセクションに対して手順を繰り返します。

17.2.5. ページヘッダーの編集

ヘッダーやフッターなどの繰り返し表示されるページ要素は、すべてポータルのデベロッパーポータルの「Partials」というセクションで定義されます。レイアウトが 1 つしかない場合、あるいは極めて少ない場合は、レイアウトコード内にヘッダーとフッターを含めることで、この手順を省略することができます。ただし、レイアウトでこれらの要素をカスタマイズするのを忘れないでください。たとえば、デフォルトの「menu」パーシャルを、実際のサイトマップに対応するように編集する必要があります。

Developer Portal Partials

17.2.6. イメージおよび他のアセットの追加

イメージまたは他のファイルについては、まずファイルをコンテンツライブラリーに読み込み、次にリンクをテキストコンテンツに挿入します。

  1. ファイルを選択するために New File を選択し、これをサイト内のどこに保存するかを指定します。
  2. イメージの URL をコピーします。
  3. これで、HTML または <a> タグを追加して、イメージの URL に貼り付けることができます。
Developer Portal add image

17.2.7. ブランディングを使用したカスタマイズ

デフォルトの default.css というスタイルシートがありますが、これは非常に大きく複雑です。これを拡張するよりも、カスタム設定で専用のスタイルシートを作成し、デフォルトを上書きする方が適切です。

ページの作成と同じ方法で、新しいスタイルシートを作成することができます。高度なページ設定で適切な MIME コンテンツタイプを選択するのを忘れないでください。次に、レイアウトテンプレートで、default.css へのリンクの後にカスタム CSS へのリンクを追加します (以下に例を示します)。

<link rel="stylesheet" href="/stylesheets/custom.css" />

17.2.8. 実稼働環境への移行

最後のタスクは、ポータルサイト全体を調べ、すべてのワークフローを確認することです。各ページまたは Changes セクションのすべてのページを公開できます。すべて問題がなければ、すべてのページが公開されていることを最終確認します。

これで、ポータルのアクセスコードを削除する準備ができました。

Developer portal access code

お疲れさまでした。これでデベロッパーポータルが公開され、開発者コミュニティー構築を支援する準備が整いました。

17.3. デベロッパーポータルの追加設定オプション

他にもデベロッパーポータルの操作箇所で、設定可能なエリアがあります。