The cisco-spark-api package

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

Cisco-spark-api package provides types and functions for accessing Cisco Spark REST API. This package is designed to improve type safety over the API. Each entity is separately typed. JSON messages contained in REST responses are decoded into appropriate type of Haskell record. JSON messages sent in REST requests are encoded only from correct type of record. Some Spark REST API returning list of objects require HTTP Link Header based pagination. Haskell functions abstract it. They automatically request subsequent pages as needed and seamlessly stream returned elements rather than just return a chunk of elements in a response. This package also provides some sample usage in command line application style. See source under app directory of the source package.


[Skip to ReadMe]

Properties

Versions0.1.0.0, 0.1.0.0
Change logCHANGELOG.md
Dependenciesaeson, attoparsec, base (>=4.7 && <5), bitset-word8, bytestring, cisco-spark-api, conduit-combinators, data-default, http-conduit, network-uri, optparse-applicative, text, utf8-string [details]
LicenseMIT
CopyrightCopyright: (c) 2017 Naoto Shimazaki
AuthorNaoto Shimazaki
MaintainerNaoto.Shimazaki@gmail.com
CategoryWeb
Home pagehttps://github.com/nshimaza/cisco-spark-api#readme
Source repositoryhead: git clone https://github.com/nshimaza/cisco-spark-api
Executablescisco-spark-api-exe
UploadedSun Oct 8 07:09:25 UTC 2017 by nshimaza

Modules

[Index]

Downloads

Maintainers' corner

For package maintainers and hackage trustees


Readme for cisco-spark-api-0.1.0.0

[back to package description]

cisco-spark-api

License: MIT Build Status Hackage Stackage Nightly Stackage LTS

A Haskell bindings for Cisco Spark API

Cisco-spark-api package provides types and functions for accessing Cisco Spark REST API. The detail of Spark API is available from developer site of Cisco Spark

This package is designed to improve type safety over the API. Each entity is separately typed. JSON messages contained in REST responses are decoded into appropriate type of Haskell record. JSON messages sent in REST requests are encoded only from correct type of record.

Some Spark REST API return list of objects. Those APIs require HTTP Link Header based pagination. Haskell functions for those APIs automatically request subsequent pages as needed. Also those functions transform chunky response into seamless stream of elements.

This package also provides some sample usage in command line application style. See source under app directory of the source package.

Sample Usage

Sending a message to a Spark Space (Room).

    let auth        = Authorization "your authorization token"
        roomId      = RoomId "Room ID your message to be sent"
        messageText = MessageText "your message"
        message     = CreateMessage (Just roomId) Nothing Nothing (Just messageText) Nothing Nothing
    createEntity auth def createMessage >>= print . getResponseBody

Following example is calling List Membership API which returns membership between Spark spaces (Room) and Spark users (Person). You can extract each Membership from Conduit pipe. The streamEntityWithFilter automatically performs pagenation when it is asked more element and last response indicated subsequent page in HTTP Link Header.

    let auth   = Authorization "your authorization token"
        filter = MembershipFilter yourRoomId Nothing Nothing
    runConduit $ streamEntityWithFilter auth def filter .| takeC 200 .| mapM_C print

You can find more examples in app/Main.hs

Support for Lens

This package provides many of records representing objects communicated via Cisco Spark REST API. Those records are designed to allow create lenses by Control.Lens.TH.makeFields.

Following example creates overloaded accessors for 'Person', 'Room' and 'Team'.

makeFields ''Person
makeFields ''Room
makeFields ''Team

You can access 'personId', 'roomId' and 'teamId' via overloaded accessor function 'id' like this.

    let yourPersonId = yourPerson ^. id
        yourRoomId = yourRoom ^. id
        yourTeamId = yourTeam ^. id

This package does not provide pre-generated lenses for you because not everyone need it but you can make it by yourself so easily as described.

Limitation