skillup

技術ブログ

アーキテクト設計全般 ドキュメント作成

APIに関して

投稿日:2020年2月27日 更新日:

RESTAPIのルーティングで気をつけることなんぞを。

直近のプロジェクトではRESTAPIを作ることが多かったんですが気をつけることなんぞを。

仕様書はソースから

web系のペースの早い現場とかだと、ドキュメントづくりが結構大変なんですよね。

ドキュメント作成について

上記のような問題点があるのですが、APIの場合は比較的ソースからドキュメントが起こしやすいのではないかと思います。

Laravelで作ったAPIのドキュメントを超簡単に生成する方法(Laravel API Documentation Generator)

私の場合、リクエストとレスポンスを伝えるのにテストコードを使っていました。

テストコードが仕様書になりますので、ソースの修正と同時に仕様書が出来上がります。(実際はそんなにうまく行きませんが手でドキュメントを作るよりかは差分が小さくなります。)

ツール

開発効率を上げるためにですが、APIを投げるツールについてよく調べておくこと

それほど調べたわけじゃないですが、やはりPostmanが使いやすかったです。

他curlコマンドを色々と応用したり、Guzzleなんかもツール化してみると使いやすいかと思います。

LaravelでのAPI実装

form以外でのPOST送信(というかHTTP通信全般)

curl コマンド 使い方メモ

命名

今回のメインはここです。

命名ルールが場当たり的になってしまい、統一性がなくなることがありましたので、ある程度一般的なルールを学習したいと思います。

基本的な原則

  • 言語の拡張子などを入れない
  • http://exmample.com/api/v1/ などバージョンを入れる
  • 名詞(できれば複数形)のみで構成するget,createなどを入れない(CRUDの分だけURLが増える)
  • URLのみで情報がわかるようにする

実例(頻出のタイプに関して)

一覧系のメソッド(GET)+新規追加

http://example.com/api/v1/articles

個別参照(GET) + 個別編集(PUT)+削除(DELETE)

http://example.com/api/v1/articles/ID番号

などでしょうか。Laravelだと一気に作ることができます。

複雑なものは、

http://example.com/api/v1/customers/100/orders/200/comments/2

などのパターンが多いようです。(リンク参照)

上記だと、顧客ID100のお客さんの注文番号200の商品の2番目のコメントみたいな感じですかね。

参考URL

RESTful APIのURI設計(エンドポイント設計)

REST APIの始め方 (名前の付け方)

REST APIとは? – API設計のポイント!

-アーキテクト設計全般, ドキュメント作成
-,

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

no image

プロジェクトマネジメントについて

ある程度、大規模なプロジェクトを経験させていただき、経験だけでなくプロジェクトマネジメントを体系的に理解しておきたいため、ポツポツと本を読んでます。 比較的初心者でも読みやすいと思った本としてを2冊メ …

no image

オブジェクト指向 ドメインモデル

本日も引き続き「現場で役立つシステム設計の原則」を読み進めてます。 本日は主にドメインモデルの考え方について。 Contents1 ドメインモデルの考え方1.1 要点1.2 感想 ドメインモデルの考え …

no image

Gitの活用に関して

今回はgitの技術的なことではなく、主に運用に関して。超基礎的なことですが、チームで開発する場合にはルールを徹底してないと混乱をきたします。 Contents1 ブランチを追加機能ごとにきる2 バグに …

no image

アプリケーションアーキテクチャについて 〜ドメインモデルに関して〜

前回のトランザクションスクリプトパターンの反省から 今回はいわゆるドメインモデルの具体例に関して。 ドメイン駆動型設計には以下のような特徴があります。 大きく、アプリケーションの構成を以下のように分け …

no image

テスト仕様書の必要な項目の定義など(横項目の定義)

前回はテストの項目をどのように作るか(分類するか)だったんですが、今回はテスト仕様書などを作る際に必要な項目の定義をまとめてみようかと。 テスト仕様書を作るとしたら前回は縦(バリデーションの組み合わせ …

アーカイブ