Git Product home page Git Product logo

hyperdrive's Introduction

Hyperdrive Logo

Hyperdrive

Hyperdrive is a generic Hypermedia API client in Swift. Hyperdrive allows you to build an application which can evolve at run-time and does not hard-code implementation details such as URIs and HTTP methods into your application. You simply enter your API using the root URI and explore it's funcitonality at run-time by understanding the semantics of the domain instead of knowledge about the implementation.

Usage

Below is a short example of using Hyperdrive to communicate with a Hypermedia API. An API that offers information about how it works at run-time using hyperlinks.

We're going to connect to a Polls API, an API which allows you to view questions, vote for them and create new questions with multiple-choice answers.

let hyperdrive = Hyperdrive()

To get started, we will enter the API from its root URI. We will pass it an asynchronous function to be executed with a result from the API.

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

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

On success, we have a Representor, this is a structure representing the API resource. It includes relations to other resources along with information about how we can transition from the current state to another.

Our client understands the semantics behind “questions” and explicitly looks for a transition to them on our API.

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

Since our API has a transition to a collection of questions, let’s retrieve them and take a look:

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

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

On success, we have another representor representing the questions resource in our 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 {
  println("Looks like there are no questions yet.")
  println("Perhaps the API offers us the ability to create a question?")
}

With every question in this resource, we will call our viewQuestion function:

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

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

Transitioning from one state to another

A representor includes information on how to transition from one state to another. For example, we might be presented with the ability to delete one of our questions:

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

We may also be presented with an option to vote on a choice:

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

Transitions with attributes

A transition may also provide attributes for performing the transition. For example, our API may afford us to perform a transition to create a new question.

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.
}

Transitions also include the available attributes you can send for run-time introspection.

create.attributes

This allows you to generate user interface that can adapt to changes from the API. You can also use validation for an attribute.

Content Types

Hyperdrive supports the following Hypermedia content-types:

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

For APIs which do not support Hypermedia content types, you may use an API description in form of an API Blueprint to load these controls.

Installation

CocoaPods is the recommended installation method.

pod 'Hyperdrive'

License

Hyperdrive is released under the MIT license. See LICENSE.

hyperdrive's People

Contributors

ayanonagon avatar fosrias avatar kylef avatar neonichu avatar zdne avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.