Hyperdrive 0.3.0

Hyperdrive 0.3.0

测试测试过
Lang语言 SwiftSwift
许可证 MIT
发布上次发布2016年6月
SPM支持 SPM

Kyle FullerZdeněk NěmecLadislav Prskavec 维护。



 
依赖
URITemplate~> 1.3
Representor~> 0.7.0
WebLinking~> 1.0
Result~> 1.0
 

Hyperdrive Logo

Hyperdrive

Hyperdrive 是一个通用的 Swift Hypermedia API 客户端。Hyperdrive 允许您构建一个可以在运行时进化的应用程序,而无需将实现细节(如 URI 和 HTTP 方法)硬编码到您的应用程序中。您只需使用根 URI 输入您的 API,然后在运行时通过理解域的语义而不是实现知识来探索其功能。

用法

以下是一个使用 Hyperdrive 与 Hypermedia API 通信的简要示例。一个提供超链接来在运行时说明其如何工作的 API。

我们要连接到 polls-api,这是一个允许您查看问题、为其投票以及创建带有多项选择答案的新问题的 API。

let hyperdrive = Hyperdrive()

为了开始,我们将从其根 URI 切入该 API。我们将传递一个异步函数来执行 API 的结果。

hyperdrive.enter("https://polls.apiblueprint.org/") { result in
  switch result {
    case .Success(let representor):
      print("The API has offered us the following transitions: \(representor.transitions)")

    case .Failure(let error):
      print("Unfortunately there was an error: \(error)")
  }
}

成功后,我们可以获取到一个 Representor,这是一个表示 API 资源的结构。它包括与其他资源的关联以及有关如何从当前状态过渡到另一种状态的信息。

我们的客户端理解“问题”背后的语义,并明确在我们的 API 上查找到它们的转换。

if let questions = representor.transitions["questions"] {
  print("Our API has a transition to a questions resource.")
} else {
  print("Looks like this API doesn’t support questions, or " +
          "the feature was removed.")
}

由于我们的 API 提供到问题集合的转换,让我们检索它们并进行查看

hyperdrive.request(questions) { result in
  switch result {
    case .Success(let representor):
      print("We’ve received a representor for the questions.")

    case .Failure(let error):
      print("There was a problem retreiving the questions: \(error)")
  }
}

成功后,我们得到另一个 Representor,代表我们的 API 中的问题资源。

if let questions = representor.representors["questions"] {
  // Our representor includes a collection of Question resources.
  // Let’s use map to call viewQuestion for each one
  map(questions, viewQuestion)
} else {
  print("Looks like there are no questions yet.")
  print("Perhaps the API offers us the ability to create a question?")
}

对于该资源中的每个问题,我们将调用我们的 viewQuestion 函数

func viewQuestion(question:Representor<HTTPTransition>) {
  print(question.attributes["question"])

  if let choices = question.representors["choices"] {
    for choice in choices {
      let text = choice.attributes["choice"]
      let votes = choice.attributes["votes"]
      print('-> \(text) (\(votes))')
    }
  } else {
    print("-> This question does not have any choices.")
  }
}

从一种状态转换到另一种状态

Representor 包含有关如何从一个状态转换到另一个状态的信息。例如,我们可能会碰到删除我们的某个问题的能力

if let delete = question.transitions["delete"] {
  // We can perform this transition with Hyperdrive
  hyperdrive.request(delete)
} else {
  print("The API doesn’t offer us the ability to delete a question.")
  print("Let’s gracefully handle the lack of this feature and " +
          "remove deletion from our user interface.")
}

我们还可能得到一个选择投票的选项

if let vote = choice.transitions["vote"] {
  hyperdrive.request(vote)
}

带有属性的转换

转换也可能提供属性以执行转换。例如,我们的 API 允许我们执行创建新问题的转换。

if let create = questions.transitions["create"] {
  let attributes = [
    "question": "Favourite programming language?",
    "choices": [
      "Swift",
      "Python",
      "Ruby",
    ]
  ]

  hyperdrive.request(create, attributes)
} else {
  // Our API doesn’t allow us to create a question. We should remove the
  // ability to create a question in our user interface.
  // This transition may only be available to certain users.
}

转换还包括可用于运行时内省的可用属性。

create.attributes

这允许您生成能够适应API变化的用户界面。您还可以为属性使用验证。

内容类型

Hyperdrive支持以下超媒体内容类型

  • Siren (application/vnd.siren+json)
  • HAL (application/hal+json)

对于不支持超媒体内容类型的API,您可以使用API Blueprint形式的API描述来加载这些控件。

安装

CocoaPods是推荐安装方法。

pod 'Hyperdrive'

其他地方

  • RxHyperdrive - 用于使用Hyperdrive的RxSwift扩展。
  • Polls Application - 与Polls超媒体API通信的iOS示例应用程序。
  • Starship - 使用Hyperdrive的iOS通用的API客户端应用程序。
  • Mockingdrive - 用于测试中轻松模拟超媒体HTTP请求的工具。

许可证

Hyperdrive是以MIT许可证发布的。请参阅LICENSE