GET https://api.website.com/v1/project/employee;company-id={company-id},
title={title-id}?non-smoker={true|false}&<name1>=<value1>&<name2>=<value2>&<name3>=<value3>
ここで、company-idは必須、titleはオプションです。name/valueは任意のフィルター基準にすることができます。
インターフェイスを定義するためのより良い方法はありますか？
このAPIは、従業員オブジェクトを作成することは想定されていません。これは、特定の会社に属し、特定の役職とその他のフィルター基準を持つ従業員オブジェクトの配列を取得するためのものです。
このAPIは、特定の会社に属し、特定の役職とその他のフィルター基準を持つ、特定の基準を満たす従業員オブジェクトをGETすることになっています。
個人的には、URIをとして設計しますhttp://acme.com/employee/?company=X&title=Y&non-smoker=Z&T=U。会社が必須であると「石で」書くつもりはありません。APIの変更が簡単になります。
ただし、多くの小さなリクエストよりもはるかに高速な「大きな」リクエストはほとんどないことを考慮する必要があります。さらに、URI表現を効果的にキャッシュできます。したがって、多くの場合、IDに基づいたURIを使用する方が適切です（再度要求される可能性が高いため）。したがって、会社の完全な従業員リスト（および会社自体に関するその他のデータ）を取得して、http://acme.com/company/Xクライアント側でフィルタリングすることができます。
使用するテクノロジーとそのイディオムに依存することが多いため、より良い方法があるかどうかはわかりません。
しかし、ここに私が好きな2つの異なるURIデザインがあります（そしてその理由）
#1 GET https://api.website.com/v1/project/employee/{company-id}?title={title-id}&non-smoker={true|false}&<name1>=<value1>&<name2>=<value2>&<name3>=<value3>
#2 GET https://api.website.com/v1/project/company/{company-id}/employee?title={title-id}&non-smoker={true|false}&<name1>=<value1>&<name2>=<value2>&<name3>=<value3>
両方の例でわかるように、クエリ文字列からcompany-idを抽出しました。パス情報に必須パラメーターを追加して、それらを区別することを好みます。次に、2番目のURIで、従業員リソースが会社にネストされます。そうすれば、特定の会社からすべての従業員を取得できることを簡単に推測できます。これは、最初の例では明らかではありません。
新しい従業員オブジェクトを作成していますか？その場合は、POST（作成）がより適切です。良い手がかりは、URLにプッシュしているすべてのデータです。これらはすべて、POSTオブジェクトの本体に含まれている必要があります。