ASP.NET Web API REST查询字符串-客户端如何知道可用的参数和选项？

使用GET公开querystring参数时，我有以下基本URL：

这将返回前25名学生

如果我想返回基于以下条件之一的学生列表，该怎么办：

* have accepted a job
* have received a job offer
* have no job offers

上述三个选项本质上是一个枚举

因此，我假设没有工作机会的学生的查询请求如下所示：

但是，我想知道jobOfferStatus=3是否是处理此问题的正确方法。如果是，我将如何向客户发布/提供该jobOfferStatus查询参数的可用选项列表？其他可能的查询参数及其有效选项如何？我们将有许多类似这样的查询参数

---

我想看一个例子，说明如何正确地完成这项工作。最佳做法是什么？

您有一些选择，让我们试着帮助您：

1） 配置到asp.net web api的通用路由知道如何解决另一个操作的名称不同于

Get

到Get方法，在

App\u Start\WebConfigApi.cs

类上，尝试添加以下内容：

config.Routes.MapHttpRoute("DefaultApiWithActionAndId",
            "api/{controller}/{action}/{id}",
            new { id = RouteParameter.Optional });

使用它，您可以在api控制器上使用不同的方法：

// request: get
// url: api/Students/GetStudents
public HttpResponseMessage GetStudents() 
{
   return Request.CreateResponse(...);
}

// request: get    
// url: api/Students/GetStudentsWithJobOffer
public HttpResponseMessage GetStudentsWithJobOffer() 
{
   return Request.CreateResponse(...);
}

// request: get    
// url: api/Students/GetStudentsAcceptedJob
public HttpResponseMessage GetStudentsAcceptedJob() 
{
   return Request.CreateResponse(...);
}

2） 在

Get

方法上使用一个简单的参数：

// request: get
// url: api/Students?jobOfferStatus=1       
public HttpResponseMessage GetStudents(int jobOfferStatus) 
{
    // use jobOfferStatus parameter to fill some list
   return Request.CreateResponse(...);
}

3） 使用名为

id

的参数的简单方法，通过asp.net mvc web api获取默认的友好url

// request: get
// url: api/Students/1      
public HttpResponseMessage GetStudents(int id) 
{
    // use the id parameter to fill some list
   return Request.CreateResponse(...);
}

---

有两个主要的选择：记录它，或者让它被发现。许多API都有文档，其中列出了供参考的所有资源和参数。否则，客户不会知道

您还可以通过在响应中包含选项，以某种方式使其可被发现。对于这方面的约定，搜索HATEOAS，如果您还没有。（我自己对HATEOAS的了解还不够，无法提出建议。）

我要提到的是，对于jobOfferStatus来说，“3”不是一个非常有意义的值，客户不需要知道这个数字。你可以做任何你想要的东西——jobOfferStatus=none，甚至jobOffer=none。控制器可以将该值与枚举进行匹配。试着为开发人员设计直观的界面（当然，还要编写好文档）

要处理多个查询参数，可以在函数中使用可选参数：

public HttpResponseMessage GetStudents(string jobOffer = "",
                                        string other1 = "",
                                        string other2 = "") 
{
    if (jobOffer == "accepted" && other2 == "whatever") {
        // return a response
    }
    else {
        // return a different response
    }
}

---

当客户机使用这些名称的参数时，您可以适当地定制您的响应。

谢谢您的帮助，但是这对客户机来说是什么样的呢？客户如何知道额外的方法？通常，客户机只知道4个主要HTTP谓词。此外，我可能需要组合多个查询参数以获得相关结果。