web-dev-qa-db-ja.com

RESTアクションとURL APIの設計に関する考慮事項

私は在庫管理システムを構築していて、APIと私のREST=実装）の設計（思考）に忙しいです。

次のリソースがあり、そのリソースで多くのアクション/操作を実行できます。各操作はリソースを変更し、場合によっては新しいリソースを作成し、履歴またはトランザクションも作成します。

URLとリソースの設計に関する有用性と許容性に関して、専門家からの意見を求めています。落とし穴と現実世界の例、意見や批判を歓迎します。

私の懸念は、この1つの大きなリソースを中心にアプリケーション全体が開発される可能性があるということです。私のバックエンドスタックはC＃とservicestackフレームワークになり、フロントエンドにはHTMLとAngularJSを使用します。それが違いを生むわけではありません。

シナリオ1.典型的な操作は次のとおりです。

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

これは、標準に関して許容されますか。他のアプローチかもしれません。

シナリオ2。

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

そして、リソースを変更します。

シナリオ3.私の意見では間違っています

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

答えを探しているのではなく、設計上の考慮事項についてのアドバイスをお探しですか？

このエントリーを読んでくれてありがとう！

restarchitectureservicestack
36
Francois Taljaard

次のリソースがあり、そのリソースで多くのアクション/操作を実行できます。各操作はリソースを変更し、場合によっては新しいリソースを作成し、履歴またはトランザクションも作成します。

RESTアーキテクチャスキーマの基本は、HTTP動詞を唯一の動詞として使用し、URLに動詞を含めないという考え方です。靴の中では、動詞を削除するためにシステムを作り直すことを考えます。動詞の意味を実際に知らずにデザインを提案することは困難ですが、おそらく以下に近いものです。

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

など..それは、よりRESTfulなアプローチです。これらのアクションの多くは、場所、数量、コメントフィールドなど、リソースの複数のプロパティを更新する単なるPUTのように見えます。そして、おそらくscrapはDELETEですか？わかりにくい。

もう1つのオプションは、POSTを使用することです。ここでは、インベントリアイテムを操作する方法についての説明が本文に含まれています。

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

これにより、すべての操作をリソースとして追跡できるようになるため、多くのトレーサビリティが得られます。欠点は、エンドポイントの周りの多くの複雑さです。

一部の「動詞」操作をリソースに分割することもできます。

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

これにより、在庫アイテムをステータスごとに簡単に確認できます。これは役立つ場合と役に立たない場合があります。たとえば、GET /returned-inventory?documentId=67890を呼び出して、同じドキュメントから返されたすべてのアイテムを取得できます。

うまくいけば、そこにいくつかの思考の糧があります。ビジネス要件をより詳細に知らなくても、だれもが「正しい」ことを行うことはできないでしょう。

40
Eric Stein

RESTful APIを定義する「Restful Objects」は、アクションが有効であることを示しています。

使用可能なアクションは、検出、有効化/無効化、「無効化された理由」フィードバックを提供できます。

アクションは、GET（クエリ）、PUT（べき等電位）、またはPOST（非べき等）を使用して「呼び出されます」

Restful Object Spec （C-125ページ）

13
Patrick

短い答え：

状態を変更するには、URLの最後にアクションを使用します。

GithubはこのようにGistにスターを付けます：PUT/gists /：Gist_id/star

ここで説明 https://developer.github.com/v3/gists/#star-a-Gist

ロングアンサー：

目的は、アプリケーションを簡単に直観的に使用できるようにすることです。ユーザーはできるだけ簡単にアプリを使用する必要があります。ユーザーは、使用するテクノロジーの制限や厳しいガイドラインに悩まされるべきではありません。

したがって、アクションと操作は本質的にリソースではなく、リソースに対するアクションです。そのため、REST is。のような「リソースからURIへのマッピング」に応答しません。

ただし、RESTの最高の機能と、依然として最高のURIの両方を組み合わせて使用​​できます。

覚えておいてください：

テクノロジーはあなたのために働くべきであり、あなたのために働くべきではありません。

テクノロジーの奴隷になると、使用できないアプリケーションを作成したり、XMLやJava Home and Remoteインターフェースなどのlikeいテクノロジーを使用したりするため、5つのファイルを作成してhello worldアプリケーションを作成することになります。 。

「光沢のあるオブジェクト症候群」に注意してください。 Google it。

テクノロジーが新しいものや「新しい方法」だからではなく、それが良いテクノロジーであるか、気を散らして他のすべてのテクノロジーをRESTに屈する必要があることを意味します。

テクノロジーから必要なものを取り出して、テクノロジーを機能させます。

REST apiを使用しても、URLおよびURIテクノロジーの機能を破棄する必要があるという意味ではありません。

参照： https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful

4
1P0