Forge API の各 API については、Forge ポータル（https://forge.autodesk.com/）から、その概要は利用方法を記したドキュメントにアクセスすることが出来ます。もちろん、開発サイクルの速いクラウド ベースの API なので、ドキュメントは英語でのみの提供になっています。
最近では、完璧とは言えないまでも、以前より簡単に Web 上の翻訳サービスを利用することも出来るので、適宜、それらを利用しながら内容を把握していただくことも可能かと思います。
ただ、ドキュメント上には、Forge ならではの解釈で使用される「用語」が存在するのも事実です。ここでは、Forge Platform ドキュメントで利用される用語について、簡単に説明を加えておくことにします。なお、「用語」は、英語ドキュメント参照を目的にするため、英語表記のままにしてあります。
API
もちろん、Application Programming Interface の略ですが、Forge Platform では、"Web API" として知られている HTTP REST API、いわゆる RESTful API を指します。同時に、個々の API 名称の基で提供される endpoint のコレクション（集合）として利用されることもあります。
例: "Model Derivative API"、"Data Management API"、"Reality Capture API"、"Fusion Connect API"
注意事項:
- "API" と言う用語は、AutoCAD のようなオートデスク製のデスクトップ製品用 API も含め、かなり広義に利用されています。Forge では、混乱や矛盾を避ける目的で、より限定的に RESTful API のみを指すように使用されています。
- JavaScript ライブラリによってWeb ブラウザ上でサポートされる "Viewer" は、HTTP REST API を利用しないため、その名称に "API" は含まれていません。"Viewer API" や "Viewing API" とは呼びません。
- Forge ポータル にリストされている "OAuth" は、内部的に RESTful API を使用しますが、一般に流通している「用語」であるため、厳密には、その名称の後に "API" は付けることはありません。決して "OAuth API" とは言いません。
個々の API の中に定義された個々の機能には、"API" を付けることはありません。例えば、Model Derivative API の 1 つの機能である変換処理（Translation）について、”Translation API” のように使用をすることはありません。
個々のサービスを示す名称に "API" を付けることはありません。例えば、Data Management API 内のサービスには、"Forge-DM API" や OSS API" のように "API" を付けることはありません。
コード ライブラリ名に "API" を付けることはありません。"JavaScript API" のように利用することはありません。
API Proxy は、論理的に関係する endpoint をグループ化したものです。API Proxy には、endpoint URI の名前空間にあたる独自のベースパスがあります。例えば、 "oauth-oss-v2-service" は、ベースパスとして https://developer.api.autodesk.com/oss/v2 にマップされています。同様に、"oauth-dm-service" は、ベースパスとして https://developer.api.autodesk.com/data/v1 にマップされています。
Platform Service API
Platform Service API は、Forge プラットフォーム API のサブセットで、従来からの存在する購入製品やサブスクリプションに依存しないものです。例えば、Model Derivative API は、ファイルへのアクセスを得るために developer（開発者）が利用する Platform Service API です。API の使用のためにオートデスク製品が直接介在するこはありません。Platform Service API は、その名称にオートデスク製品名やブランド名が含まれることはありません。
Product API
Platform Service API は、Forge プラットフォーム API のサブセットで、従来からの存在する購入製品やサブスクリプションに依存するものです。例えば、Fusion Connect API は、既存の Fusion Connect（旧名 "SeeControl"）サブスクリプションの環境で使用する Product API です。特定の機能を一般化したり、Microservice 指向の API を指すものではありません。また、Platform Service API と重複することはありません。
endpoint は、単一の URI で示される単一の HTTP リソースです。API proxy は、与えられたベースパス配下の URI 名前空間で、1 つ以上の endpoint から構成されています。また、endpoint は、デベロッパ ポータル上では個々の API を表現していて、機能別に通常グループ化されています。
例えば、次の endpoint は、OSS bucket の詳細を取得するためのものです。
https://developer.api.autodesk.com/oss/v2/buckets/:bucketKey/details
- この endpoint の表示名は: GET buckets/:bucketKey/details
- この endpoint のドキュメント中の url_path は: bucket-:bucketKey-details-GET
- この endpoint のドキュメント上のフルパスは: https://developer.autodesk.com/en/docs/data/v2/reference/http/bucket-:bucketKey-details-GET
- この endpoint 用にドキュメントに含まれる RST ファイルの api_documentation repository 内の source ファイル名は: bucket-bucketKey-details-GET.rst
- RST ファイルのフルパスは: cloudplatform-apim/api_documentation:dev/data/v2/reference/http/bucket-bucketKey-details-GET.rst
- endpoint grouping（endpoint グループ） は: Object Storage
- この endpoint の API proxy は: oauth-oss-v2-service
- この endpoint のベースパスは: /oss/v2/
- この endpoint にアクセスすることが出来る API Product は: Data Management API
- この endpoint の service（サービス）は: OSS (v2)
いくつかのケースでは、サービス/API が API 呼び出しを満たすべく、開発者（developer）に地理的な地域を指定させるために、個別の endpoint が分離した URI を持つようデザインされたものがあります。これは、前述のルールの例外で、ドキュメント上に明記されているはずです。
endpoint grouping
デベロッパー ポータルに適用される、機能によって endpoint を論理的にグループ化するコンセプトです。endpoint グループ化は、 API ドキュメントの "HTTP Specification" セクションに明記されています。
service
文脈によっては、"service" は、オートデスク社内でサービスを開発している開発チーム "service team" と同義語となる場合もあります。多くの場合、各 API の一連の機能（論理的な機能群）を表します。稀に 1 つのサービスが複数の他のサービスで作られる場合もあります。これらのサービスは、オートデスクが外部に公開している API を直接サポートしたり、個別の API 内で機能となるバックエンド サービスです。
library
library は、クラス、メソッド、その他、 Viewer を含むオートデスクの API の利用に便利な、再利用可能な言語固有セットです。それらは、内部で素の HTTP REST 呼び出しを おこない、HTTP REST 呼び出しをラップします。
言語固有のライブラリは GitHub.com 上に "Autodesk-Forge" 配下のリポジトリでホストされています。歴史的には、それらを "SDK" と呼ぶかも知れませんが、正確には、library は "software development kits" ではありません。
tutorial
API 使用時の個別の手順やワークフローを解説するもので、"guide" や "step-by-step tutorial"、または、 "step-by-step guide" と同義です。はじめに習得すべき、"Hello, world!" サンプル的な内容を達成するアクションが記されています。例えば、Extensions tutorial for the Viewer を確認してみてください。
REST API では、tutorials は cURL コマンドを使用しているはずです。 言語固有のライブラリが存在する場合には、それらも使用することもあります。より複雑な例を示す場合には、tutorial ではなく、code sample が用意されます。
code sample
tutorial とは異なり、ステップ毎のガイドは提供ません。 通常、developer（開発者）の API 習得のスタートポイントとなったり、実際の開発作業に活用したり出来る、より複雑で強力な例を含んでいます。例えば、ある code sample では、iOS に Viewer を統合するサンプルが提供されています。このようなサンプルは、tutorial には複雑すぎます。なお、提供される code sample は、すべてのシナリオにおいて完全でない場合もありますのでご注意ください。
code sample は、 GitHub.com 上の "Autodesk-Forge" 名前空間にホストされています。また、code sample は、デベロッパー ポータルの "Code Samples" セクションから参照することが出来ます。各 code sample リポジトリのトップ ページには、README.md にサンプルの機能と使用手順などの概要が提供されています。
StakOverflow tag
各 API は、固有の StackOverflow タグを持ち、developer は質問を適切にタグ付けすることが出来ます。これらのタグは、デベロッパー ポータル上の StackOverflow 検索機能に統合されています。
developer
Forge API を利用する 3rd party、つまり、オートデスク以外の外部の開発者を意味します。
3D , 2D
3 次元や 2 次元を意味するもので、3d や 2d（d が小文字）の用語では用いません。
デベロッパー ポータル上のドキュメントを読み解く上で参考にしてみてください。
By Toshiaki Isezaki
Subscribe
コメント