Skip to content

the-hypermedia-project/representor-swift

Repository files navigation

Representor in Swift

Swift library for building and consuming Hypermedia messages. See The Hypermedia Project Charter for details.

Installation

Swift Package Manager

Representor can be installed via the Swift Package Manager by adding Representor as a dependency in your Package.swift:

.Package(url: "https://github.com/the-hypermedia-project/representor-swift.git", majorVersion: 0, minor: 7)

CocoaPods

Representor can be installed with CocoaPods by adding Representor to your Podfile:

pod 'Representor'

Sub-projects

Alternatively, you can clone Representor via git or as a submodule and include Representor.xcodeproj inside your project and add Representor.framework as a target dependency.

Usage

Using the builder pattern to build a representor

import Representor

let representor = Representor<HTTPTransition> { builder in
    builder.addTransition("self", uri:"/notes/2/")
    builder.addTransition("previous", uri:"/notes/1/")
    builder.addTransition("next", uri:"/notes/3/")

    builder.addMetaData("title", "Customer Details")

    builder.addTransition("create", uri:"/notes/") { transitionBuilder in
        transitionBuilder.method = "POST"
        transitionBuilder.addAttribute("title")
        transitionBuilder.addAttribute("note")
    }
}

Consuming a representor

if let create = representor.transitions["create"] {
    print("You can create with the URI: \(create.uri).")
}

if let next = representor.transitions["next"] {
    print("The next representor can be found at: \(next).")
}

if let prev = representor.transitions["previous"] {
    print("The previous representor can be found at: \(prev).")
}

Adapters

The representor includes adapters to convert between other hypermedia types.

NSHTTPURLResponse

You can initialise a representor using a NSHTTPURLResponse and the body (NSData). It will use the content-type from the response and deserialise the body payload into a format. For unsupported/unknown types, nil will returned.

let representor = HTTPDeserialization.deserialize(response, body: body)

You can register your own, or overide an existing HTTP deserializer for a specific content type.

HTTPDeserialization.deserializers["application/json"] = { response, body in
  return Representor(...)
}
Supported Media Types
  • HAL JSON (application/hal+json)
  • Siren JSON (application/vnd.siren+json)

HAL

You can explicitly convert to and from a HAL representation using the following.

let representor = deserializeHAL(representation)
let representation = serializeHAL(representor)

Siren

Conversion to and from a Siren representation can also be done using the following.

let representor = deserializeSiren(representation)
let representation = serializeSiren(representor)

License

Representor is released under the MIT license. See LICENSE.