LPMSirenKit 是一个轻量级的库，用于与遵从 Hypermedia APIs 的且符合 Siren 规范的 API 进行交互。

LPMSirenKit 基于 AFNetworking 并代表应用程序提交请求。该库将解析结果并缓存实体、链接、动作和字段对象。在此级别不会被缓存实体对象的 properties（库只会缓存导航所需的东西）。

使用方法

运行示例项目

克隆仓库

$ git clone [email protected]:lonelyplanet/lpm-sirenkit-ios.git

切换到示例目录

$ cd lpm-sirenkit-ios/Example

运行 Pod Install 下载示例项目依赖

$ pod install

打开 LPMSirenKit.xcworkspace

$ open LPMSirenKit.xcworkspace

现在您可以从 Xcode 运行项目。一旦应用程序启动，您将看到一个要求输入您要在其上运行应用程序的服务器 URL 和声明位置的屏幕。根据我们的定义，声明是初始 SirenEntity 的位置。对于大多数服务器，您可以保留此字段为空，因为初始 SirenEntity 位于您指定的根 URL 的根目录。

LPMSirenKit 的典型使用流程

初始化

您将使用基础 URL、API 声明文件的路径和 NSURLSessionConfiguration 实例（defaultSessionConfiguration 工作得非常好）来创建一个 LPMSirenSessionManager。声明简单来说就是 API 的根目录或者，更确切地说，API 指示哪些根级链接和/或动作可用于初始化您的 LPMSirenSessionManager。

LPMSirenSessionManager *sirenSessionManager = [[LPMSirenSessionManager alloc] initWithBaseURL:[NSURL URLWithString:@"http://siren.api"]
                                                                                 manifestPath:manifestPath
                                                                         sessionConfiguration:NSURLSessionConfiguration.defaultSessionConfiguration];

请求清单

接下来，您需要请求清单

[sirenSessionManager GETManifestWithParameters:nil completion:^(LPMSirenEntityModel *manifestEntity, NSError *error) {
  // Check manifestEntity and error to determine if request was successful
}];

当您请求清单时，您正在获取初始的 SirenEntity，这是您开始遍历 API 的地方。此实体可能包含 API 的高级 SirenLinks 和 SirenActions。

请求链接

成功请求 API 的清单后，您可以开始使用 API 了。如果您使用与清单 LPMSirenEntityModel 相关联的 LPMSirenLinkModel（因为清单只是一个 LPMSirenEntityModel，您可以通过检查 manifestEntityModel.sirenLinks 关系来找到任何您希望使用的 LPMSirenLinkModel），通过使用 LPMSirenLinkModel 来请求链接

[sirenSessionManager GETLink:sirenLinkModel withParameters:nil completion:^(LPMSirenEntityModel *sirenEntityModel, NSError *error) {
  // Check sirenEntityModel and error to determine if request was successful
} error:&error];

或通过使用链接的关系以及拥有该链接的实体的 GUID

[sirenSessionManager GETLinkForRelationship:@"self" ofEntityWithGUID:@"guid" withParameters:nil completion:^(LPMSirenEntityModel *sirenEntityModel, NSError *error) {
  // Check sirenEntityModel and error to determine if request was successful
} error:&error];

如果 LPMSirenLinkModel 未在在 LPMSirenKit 的本地缓存中通过请求方法找到，则 GETLinkForRelationship:ofEntityWithGUID:withParameters:completion:error: 将返回 nil，而不是有效的 NSURLSessionDataTask，并且 NSError 参数中将给出错误代码 SirenKitError_ErrorCode_LinkNotFound。

提交操作

您可以通过使用具有参数字典的 LPMSirenActionModel 来提交操作

[sirenSessionManager HTTPActionWithSirenAction:sirenActionModel withParameters:parameters completion:^(LPMSirenEntityModel *sirenEntityModel, NSError *error) {
  // Check sirenEntityModel and error to determine if request was successful
} error:&error];

或通过使用操作的名字和拥有该操作的实体的 GUID

[sirenSessionManager HTTPActionWithName:@"action" onEntityWithGUID:@"guid" withParameters:parameters completion:^(LPMSirenEntityModel *sirenEntityModel, NSError *error) {
  // Check sirenEntityModel and error to determine if request was successful
} error:&error];

如果 LPMSirenActionModel 未在 LPMSirenKit 的本地缓存中通过请求方法找到，则 HTTPActionWithName:onEntityWithGUID:withParameters:completion:error: 将返回 nil，而不是有效的 NSURLSessionDataTask，并且 NSError 参数中将给出错误代码 SirenKitError_ErrorCode_ActionNotFound。

LPMSirenKit 将尝试将操作请求给出的参数映射到与该操作关联的字段。任何在参数字典中没有相应 LPMSirenFieldModel 为指定 LPMSirenActionModel 的密钥将在请求中忽略（通过 name 属性匹配）。如果您尝试设置隐藏字段的值，则此值将在请求中忽略。此外，LPMSirenKit 还尝试进行类型匹配。例如，如果一个字段指示它是一个 number 或 url 输入类型，LPMSirenKit 将验证为这些键给出的值是否与相同类型匹配（即 NSNumber 或 NSURL）。如果类型不匹配，则 NSError 参数中将给出错误代码 SirenKitError_ErrorCode_FieldTypeMismatch。

认证 API

您是否在与认证的 Siren API 进行交互？酷！我们（孤独星球）也在做同样的事情。 LPMSirenSessionManager 支持使用 HTTP 授权头。只需设置 authorizationHeaderValue 属性，所有后续请求都将包含该头

sirenSessionManager.authorizationHeaderValue = @"Bearer some-hex-string";

什么是 GUID？

每个实体都需要一个全局唯一标识符。然而，不同的 API 使用不同的标识符，且在同一个 API 中，不同类型/种类的实体可以使用不同的标识符。 LPMSirenSessionStore 有一个方法允许客户端指定对于每种类型的实体，这些 GUID 可以在哪里找到。

[LPMSirenSessionStore setGUIDMappingDictionary:@{
                                              @"order": @"properties.orderNumber",
                                              @"items, collection": @"href",
                                              @"info, customer": @"properties.customerId"
                                              }];

在上面的场景中，键应与实体的 class 匹配。在响应解析为 LPMSirenEntityModel、LPMSirenLinkModel 或 LPMSirenActionModel 之后，value 将是标识符的路径。

如果我想为一个放置/集合实体的 GUID 设置该实体的 'self' 链接，映射可能看起来像这样

@"places, collection": @"sirenLinks[0].href" // First link is usually 'self'

或者

@"places, collection": @"sirenLinks[@rel~self].href" // A link whose rel property contains the 'self' identifier; This means rel could be "self" or "this, self" and it would be found

或者甚至

@"places, collection": @"sirenLinks[@rel=self].href" // A link whose rel property is equal to the 'self' identifier; This means rel has to be "self" to be found

核心数据依赖

LPMSirenKit 目前使用 Core Data 缓存从服务器解析响应时的 Siren 相关元数据。这有助于在后续请求之前快速回忆服务器支持哪些实体、链接和操作。 LPMSirenKit 使用内置的数据存储，您作为开发者不必担心或维护它。有关此数据存储的更多信息，请查看 LPMSirenKit.xcdatamodeld、ManagedSirenEntity、ManagedSirenLink、ManagedSirenField 和/或 ManagedSirenAction。

要求

LPMSirenKit 依赖于几个其他库：AFNetworking、CoreDataMate、LPMJSONUtils 和 Mantle。这些作为依赖项包含在 .podspec 中，并且将在将 LPMSirenKit 添加到 Podfile 后运行 pod install 时安装。

安装

LPMSirenKit 通过 CocoaPods 提供。要安装它，只需将以下行添加到您的 Podfile 中

pod 'LPMSirenKit'

作者

Todd Grooms，[email protected]

许可协议

LPMSirenKit 在 MIT 许可协议下可用。有关更多信息，请参阅 LICENSE 文件。