catch-img

【解説】APIドキュメント(テンプレート)

本日は、普段開発時に使っているAPIドキュメントテンプレートを共有します(今後様々なドキュメントテンプレートを共有していく予定です)。

サービス開発の際にドキュメントはないがしろにしがちですが、大切なプロセスなので面倒でもきちんと書き起こしましょう。特にチームで開発する場合、ドキュメントが中心となりチーム全員の理解が統率されていきます。仕様変更時は、ドキュメントも随時更新して常に正しいものにしていく運用も大切です。設計時に書き起こした仕様書が全く(よくも悪くも進化した)システムと合っていなくて意味がない・・・、なんていうシーンはあるあるですね・・ ・

APIドキュメントに関しては、他の人に利用されるものなのでレベルの高いドキュメントが必要とされます。レベルが高いといっても複雑なものではなく、むしろ、できるだけ短く簡素かつわかりやすく書く必要があります。


(API名を記載)

APIの説明文を記載。APIの利用シーンと目的を記載すると、使う人にもわかりやすい。


URL(APIの相対パス)


メソッド

GET | POST | DELETE | PUT のいずれかを記載。


URLパラメーター

リクエスト時に使えるパラメーターを記載。

必須パラメーター

必須となるパラメターを記載。 パラメーターは

  • パスで渡すもの
  • クエリーで渡すもの
  • クッキーで渡すもの

があります。明記してAPI利用者にわかりやすくしましょう。

オプションパラメーター

必須パラメーターと基本同じフォーマットで記載。

データ

POST時に渡すデータを記載。データのタイプとしては

  • application/json
  • application/xml
  • application/x-www-form-urlencoded
  • text/plain
  • multipart/form-data

があります。入力値エラーがおきないように各値のタイプや制限を明記しましょう。


正常レスポンス

コード200


エラーレスポンス

エラーレスポンスの一覧を記載。エラーコード一覧はこちらを参照: 

https://docs.microsoft.com/en-us/rest/api/storageservices/common-rest-api-error-codes


サンプルコード

サンプルコードを記載。cURLを使ってAPIを使う方法はこちらを参照:https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/Developers/GettingStarted/API%20requests/curl-requests.htm


備考

備考を記載 。


ECXサイト編集部
ECXサイト編集部

トランスコスモスのECX本部が運営するサービスサイト「ECX」編集部です。コーディング、WEBデザイン、SEM、UI改善などの実務経験豊富なメンバーで執筆・運営・管理をしております。

関連記事


【無料】セミナー動画視聴

2021年7月13日オンラインECセミナー動画【無料視聴】

デジタルシフトが求められる今、D2Cへの関心が高まり、ダイレクトにお客様とつながる D2C ビジネスは注目を集めています。本セミナーでは、顧客視点で取り組むD2CとEC事業を成功させるために不可欠なプラットフォーム『Shopify』の歴史・メリットなど基本のすべてをお伝えさせていただきます。

2021年1月27日オンラインECセミナー動画【無料視聴】

トランスコスモスのEC支援に対する豊富な実績をもとに今後の変革に必要と考えられる「CRM、データドリブン、生産性向上」をテーマとした当社コンサルティングサービスについて、講義形式のセミナー開催

2020年11月30日オンラインECセミナー動画【無料視聴】

【Shopify構築・運用セミナー】拡大するEC市場に不可欠なバックエンド業務の最新トレンド。EC事業を成功させるために『効率化に向けたバックエンド業務の最新トレンド』と題して、Shopify構築・運用に連携できるサービスをご紹介。


EC関連サービス

お気軽に
お問い合わせください

Shopify(ショッピファイ) ECストア構築・運用代行

トランスコスモスは日本に6社しかない最上位の「Shopifyプラスパートナー」企業です

Shopify人気記事ランキング

 Tag(タグ)

 記事検索

 カテゴリー

 【無料】募集中セミナー

全9件中 1〜 4件を表示

 【無料】資料ダウンロード

Shopify操作マニュアルのダウンロード一覧

ショッピファイの管理画面の使い方を図解で開設した操作マニュアル資料をPDFにてダウンロード頂けます。

ECサービス紹介資料無料ダウンロード一覧

トランスコスモスのEC関連のサービス資料の一覧ページです。PDFにて概要のわかる資料を「無料」でダウンロードして頂けます。

セミナー発表資料の無料ダウンロード一覧

トランスコスモスのEC関連のWEBセミナーで使用した資料一覧ページです。PDFにてセミナーの内容がわかる資料を「無料」でダウンロードして頂けます。

全3件中 1〜 3件を表示

Shopify認定パートナー企業

トランスコスモスは日本に7社しかない最上位の「Shopifyプラスパートナー」です。
Shopifyでのサイト制作ならお任せください