原文链接 ： https://futurestud.io/tutorials/retrofit-2-basics-of-api-description
在上一篇教程 开始使用Rirtofit 中，我们已经对一个 Git 端点实现了第一个请求。希望你正对使用 Retrofit 的更多功能感到跃跃欲试，在本篇教程中，你将学习到关于 Retrofit 如何描述 API 端点的更多细节。
如何描述API端点
正如我们上一个教程所学到的，我们在一个接口类中描述所有的Retrofit请求。我们的第一个例子向我们展示了Retrofit的多个功能。
public interface GitHubClient {
@GET("/users/{user}/repos")
Call<List<GitHubRepo>> reposForUser(
@Path("user") String user
);
}
现在是时候让我们进一步了解这些功能的细节。
HTTP方法
我们已经知道 Retrofit 通过在 Java 接口方法上使用注释来描述各个 API 端点，最后才描述如何去处理这些请求。我们需要做的第一件事就是定义 HTTP 请求方法，如 GET, POST,PUT, DELETE 等等。Retrofit 为每个主要的标准请求方法提供了注释，我们只需简单的为每个HTTP方法使用对应的注释： @GET,@POST, @PUT, @DELETE, @PATCH 或者 @HEAD。
我们总是需要为程序使用的API指定请求方法。如果你对HTTP请求方法还不太了解，请参阅WIKI相关页面。 一般情况下，你应该可以从API文档找到恰当的请求方法。
下面是使用了 @GET、@PUT 、 @DELETE 的几个简单例子 ：
public interface FutureStudioClient {
@GET("/user/info")
Call<UserInfo> getUserInfo();
@PUT("/user/info")
Call<UserInfo> updateUserInfo(
@Body UserInfo userInfo
);
@DELETE("/user")
Call<Void> deleteUser();
}
HTTP资源地址
另外，我们需要把端点的相对 URL 作为 String 参数添加到注释中，例如：@GET("/user/info")。在大多数情况下，我们只需传入相对 URL，而不传入完整 URL（如 http://futurestud.io/api/user/info ），这么做的好处是，Retrofit 只需要请求一次基本 URL（ http://futurestud.io ）。如果你需要改变 API 的基本 URl，只需要在一个地方进行修改。此外，这使得一些先进的东西，比如动态基础 URL，使用起来更加方便。不过你依然可以指定一个完整 URL。如果你希望学习更多关于 URl 的处理以及 基础 URL 与 相对 URL 的组合方式，请随时阅读我们的 URL 的处理和分析 指南。
再次给出几个简单例子：
public interface FutureStudioClient {
@GET("/user/info")
Call<UserInfo> getUserInfo();
@PUT("/user/info")
Call<UserInfo> updateUserInfo(
@Body UserInfo userInfo
);
@DELETE("/user")
Call<Void> deleteUser();
// example for passing a full URL
@GET("https://futurestud.io/tutorials/rss/")
Call<FutureStudioRssFeed> getRssFeed();
}
方法名与返回值类型
现在你已经知道了如何使用HTTP请求方法注释了，然而我们还没有谈到实际的 Java 方法声明，Call<UserInfo> getUserInfo();，这包含了三个部分：
- 1 方法名
- 2 返回值类型
- 3 方法参数
我们从容易的一个开始：方法名。我们可以自由的定义方法名，Retrofit 不在意你如何定义方法名，且对功能没有任何影响。不过，我们还是应该定义一个有助于自己和其他开发者了解这是什么API请求的名称。
另一方面，方法的返回值相当关键。必须定义你预期从服务器获得的数据类型。例如，当你正在请求某些用户信息时，你可能会像这样指定： Call<UserInfo>。UserInfo 类包含了用于保存用户数据的变量。Retrofit将会自动进行映射，不需要进行任何手动解析。如果您想要获取原始响应，可以使用 ResponseBody 替换 UserInfo 这样的自定义类。如果完全不关心服务的响应数据，你可以使用 Void。在这种情况下，必须将它包装成一个 Retrofit 的 Call<> 类。
最后，你可以给方法传递参数，这很大程度取决于 API 端点的需要。方法参数存在非常多的选择，所以这里只给出其中几个例子：
@Body : 发送Java对象作为请求体
@Url : 使用动态 URL
@Field : 发送表单数据
再次给出几个用例：
public interface FutureStudioClient {
@GET("/user/info")
Call<UserInfo> getUserInfo();
@PUT("/user/info")
Call<Void> updateUserInfo(
@Body UserInfo userInfo
);
@GET
Call<ResponseBody> getUserProfilePhoto(
@Url String profilePhotoUrl
);
}
路径参数
REST标准的API是建立于动态URL上的，你可以通过替换URL的某部分来获取资源，例如获取我们页面的第三篇教程的URl可能为 http://futurestud.io/api/tutorials/3，末尾的 3 指定了你想要访问哪一篇教程。Retrofit提供了一种可以方便地替换这些路径参数的方式。在入门教程中我们已经看到过一个简单的例子：
public interface GitHubClient {
@GET("/users/{user}/repos")
Call<List<GitHubRepo>> reposForUser(
@Path("user") String user
);
}
在这里{user}告诉 Retrofit 这个值是动态的，且该值将在请求开始时配置。如果你使用的URl包含了一个路径参数，那么你必须在方法中添加一个 @Path 参数，@Path的值会与URL中的占位符匹配（在上面的例子中为 @Path("user") ）。如果需要，你可以使用多个占位符，只要你能够确保有合适的可供匹配的参数即可。你甚至可以使用可选路径参数。
查询参数
动态URl的另一大部分是查询参数。如果你已经使用过过滤器，你会在我们的页面上看到 https://futurestud.io/tutorials?filter=video。其中 ?filter=video 就是进一步描述所需查找资源的查询参数。与路径参数不同的是，你不需要将他们添加到URL注释中。你可以非常方便地在方法中添加一个带有 @Query() 和查询参数名的参数，然后描述参数的类型就可以了。Retrofit会自动把它附加到请求中。如果将 null 作为值传入查询参数中，Retrofit会忽略它。你还可以添加多个查询参数。
public interface FutureStudioClient {
@GET("/tutorials")
Call<List<Tutorial>> getTutorials(
@Query("page") Integer page
);
@GET("/tutorials")
Call<List<Tutorial>> getTutorials(
@Query("page") Integer page,
@Query("order") String order,
@Query("author") String author,
@Query("published_at") Date date
);
}
在上面的例子中，你也可以删除第一个 getTutorials() 方法，通过在第二个方法的后三个参数传入 null 值的方式来实现和第一个方法一样的效果。
接下来
现在你已经学会了如何为接口添加新的API端点，调整URL地址，HTTP方法，返回值类型，路径和查询参数等，但是这仅仅是入门而已。
Retrofit 提供了非常多的选项来进一步完善网络数据请求。例如，我们还没有聊到 Header 呢。要学习的还有很多，所以让我们继续更多的教程吧！
如果您有什么反馈或者问题，请在 Twitter 里 @futurestud_io。
Make it rock & enjoy coding!
