-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Unofficial Haskell Client Library for the Orchestrate.io API -- @package OrchestrateDB @version 1.0.0.3 -- | This module conatins Haskell types which represent all necessary JSON -- patterns used by the Orchestrate.io API. module Database.Orchestrate.Types -- | A data type, that represents an Orchestrate application. It stores an -- api key (generated online) and a https-endpoint. data OrchestrateApplication OrchestrateApplication :: String -> String -> String -> OrchestrateApplication applicationName :: OrchestrateApplication -> String apiKey :: OrchestrateApplication -> String httpsEndpoint :: OrchestrateApplication -> String -- | Represents a collection inside an OrchestrateApplication, it stores -- all data necessary to access it. data OrchestrateCollection OrchestrateCollection :: String -> OrchestrateCollection collectionName :: OrchestrateCollection -> String -- | Haskell type for the JSON scheme, that is returned by the SEARCH -- function. data OrchestrateQueryResult OrchestrateQueryResult :: OrchestratePath -> Object -> Double -> Integer -> OrchestrateQueryResult orchestrateQueryResultPath :: OrchestrateQueryResult -> OrchestratePath orchestrateQueryResultValue :: OrchestrateQueryResult -> Object orchestrateQueryResultScore :: OrchestrateQueryResult -> Double orchestrateQueryResultReftimeQueryResult :: OrchestrateQueryResult -> Integer -- | Represents a path, as it is returned by the LIST and SEARCH function. -- Right now it is not actually used, but it might be useful in the -- future. data OrchestratePath OrchestratePath :: String -> String -> String -> String -> Integer -> OrchestratePath orchestratePathCollection :: OrchestratePath -> String orchestratePathKind :: OrchestratePath -> String orchestratePathKey :: OrchestratePath -> String orchestratePathRef :: OrchestratePath -> String orchestratePathReftime :: OrchestratePath -> Integer -- | Haskell type for the JSON scheme, that is returned by the LIST -- function. data OrchestrateListResult OrchestrateListResult :: OrchestratePath -> Object -> Integer -> OrchestrateListResult orchestrateListResultPath :: OrchestrateListResult -> OrchestratePath orchestrateListResultValue :: OrchestrateListResult -> Object orchestrateListResultReftimeQueryResult :: OrchestrateListResult -> Integer resultValuesAsList :: OrchestrateIntermediateResult a => [a] -> [Object] instance Show OrchestrateApplication instance Read OrchestrateApplication instance Eq OrchestrateApplication instance Show OrchestrateCollection instance Read OrchestrateCollection instance Eq OrchestrateCollection instance Show OrchestratePath instance Read OrchestratePath instance Generic OrchestratePath instance Show OrchestrateQueryResult instance Generic OrchestrateQueryResult instance Show OrchestrateListResult instance Generic OrchestrateListResult instance Datatype D1OrchestratePath instance Constructor C1_0OrchestratePath instance Selector S1_0_0OrchestratePath instance Selector S1_0_1OrchestratePath instance Selector S1_0_2OrchestratePath instance Selector S1_0_3OrchestratePath instance Selector S1_0_4OrchestratePath instance Datatype D1OrchestrateQueryResult instance Constructor C1_0OrchestrateQueryResult instance Selector S1_0_0OrchestrateQueryResult instance Selector S1_0_1OrchestrateQueryResult instance Selector S1_0_2OrchestrateQueryResult instance Selector S1_0_3OrchestrateQueryResult instance Datatype D1OrchestrateListResult instance Constructor C1_0OrchestrateListResult instance Selector S1_0_0OrchestrateListResult instance Selector S1_0_1OrchestrateListResult instance Selector S1_0_2OrchestrateListResult instance OrchestrateIntermediateResult OrchestrateListResult instance ToJSON OrchestrateListResult instance FromJSON OrchestrateListResult instance OrchestrateIntermediateResult OrchestrateQueryResult instance ToJSON OrchestrateQueryResult instance FromJSON OrchestrateQueryResult instance ToJSON OrchestratePath instance FromJSON OrchestratePath -- | This module conatins all the functions which interact with the -- Orchestrate.io REST API. Right now these actions are supported: -- -- module Database.Orchestrate.REST -- | The validateApplication function validates your API key, by -- making an authenticated HEAD request to the endpoint specified in the -- OrchestrateApplication record. The function returns False when -- the key is invalid or no connection with the endpoint could be -- established. validateApplication :: OrchestrateApplication -> IO Bool -- | The orchestrateCollectionPutWithoutKey function stores a -- Haskell value(with a ToJSON instance) in an Orchestrate.io -- database. It does so by making a POST request to the /$collection -- endpoint(Offical API -- docs:https://orchestrate.io/docs/apiref#keyvalue-post). This -- function does not need a user specified key, because it uses a -- server-generated key, if you want to know the key use -- orchestrateCollectionPut instead of this function. -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   _ <- DB.orchestrateCollectionPutWithoutKey dbApplication dbCollection testRecord
--   
--
orchestrateCollectionPutWithoutKey :: ToJSON obj => OrchestrateApplication -> OrchestrateCollection -> obj -> IO Bool -- | The orchestrateCollectionDelete function deletes a collection -- from an Orchestrate.io application. This is done by making a DELETE -- request to the /$collection endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#collections-delete) -- --

Example:

-- -- 
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   _ <- DB.orchestrateCollectionDelete dbApplication dbCollection
--   
--
orchestrateCollectionDelete :: OrchestrateApplication -> OrchestrateCollection -> IO Bool -- | The orchestrateCollectionGet function request a value from an -- Orchestrate.io database, and tries to convert it to the specified -- Haskell type, if either gettings the value from the database or -- converting it to the Haskell type fails Nothing is returned. -- The value is requested by making a GET request to the -- /$collection/$key endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#keyvalue-get) -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   dbValue <- DB.orchestrateCollectionGet dbApplication dbCollection KEY :: IO (Maybe TestRecord)
--   
--
orchestrateCollectionGet :: FromJSON res => OrchestrateApplication -> OrchestrateCollection -> String -> IO (Maybe res) -- | The orchestrateCollectionPut function stores a Haskell -- value(with a ToJSON instance) in an Orchestrate.io database. It -- does so by making a PUT request to the /$collection/$key -- endpoint(Offical API -- docs:https://orchestrate.io/docs/apiref#keyvalue-put). In order -- to upload a Haskell Value to the database, it must have an instance of -- ToJSON because this client library uses Aeson to convert -- Haskel Values to JSON, which is required by Orchestrate.io. -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   _ <- DB.orchestrateCollectionPutWithoutKey dbApplication dbCollection KEY testRecord
--   
--
orchestrateCollectionPut :: ToJSON obj => OrchestrateApplication -> OrchestrateCollection -> String -> obj -> IO Bool -- | The orchestrateCollectionDeleteKey function deletes a value -- from an Orchestrate.io database. This is done by making a DELETE -- request to the /$collection/$key endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#keyvalue-delete) -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   _ <- DB.orchestrateCollectionKey dbApplication dbCollection KEY
--   
--
orchestrateCollectionDeleteKey :: OrchestrateApplication -> OrchestrateCollection -> String -> IO Bool -- | Please see orchestrateCollectionSearchWithOffset for more -- information. This function just calls it without an offset and with a -- limit of 10. orchestrateCollectionSearch :: OrchestrateApplication -> OrchestrateCollection -> String -> IO (Maybe ([Object], Bool)) -- | The orchestrateCollectionSearchWithOffset function searches for -- the query in the database and returns an array of the type -- "Maybe [Object]". Nothing is returned when establishing -- a connection or authenticating failed. The function uses the SEARCH -- method of the Orchestrate.io API (Offical -- documentation:https://orchestrate.io/docs/apiref#search-collection) -- , but automatically parsers the response. It returns a tupel of the -- type (Maybe([Object],Bool)), the boolean -- indicates wether or not more results are availble on the server. If -- that is true, the function should be called again with an increased -- offset, until (Just _,False) is returned. -- --

Example:

-- -- 
--   dbSearchResults query num =
--       let results = DB.orchestrateCollectionSearchWithOffset query num (num+10)
--       let currentResults = fromJust $ fst results
--       if snd results
--          then currentResults:(dbSearchResults query (num+10))
--          else currentResults
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let completeDBSearchResults = dbSearchResults QUERY 0
--   
--
orchestrateCollectionSearchWithOffset :: OrchestrateApplication -> OrchestrateCollection -> String -> Integer -> Integer -> IO (Maybe ([Object], Bool)) -- | The orchestrateCollectionList function lists the contents of -- the specified collection, by making GET request to the -- /$collection?limit=$limit endpoint. For more information check out the -- Orchestrate.io API docs: -- https://orchestrate.io/docs/apiref#keyvalue-list. If connecting -- to the api fails, or the api key stored in the application record is -- invlaid, Nothing is returned. Otherwise an array of the type -- Object(see the documentation of Aeson for more -- information) is returned, it contains the values from the HTTP -- response(see https://orchestrate.io/docs/apiref#keyvalue-list -- for an example of how the response looks like in JSON). -- --

Example:

-- -- 
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   dbContents <- DB.orchestrateCollectionList dbApplication dbCollection 10
--   
--
orchestrateCollectionList :: OrchestrateApplication -> OrchestrateCollection -> Integer -> IO (Maybe [Object]) -- | This library implements most parts of the Orchestrate.io API in -- Haskell. It provides a convenient way of accessing these parts of the -- REST API: -- -- -- -- NOTE: You can also use Curl, if you need one of the currently -- unsupported API functions, but you would have to parse all response -- bodies yourself if you do that. -- --

How to use this library?

-- -- Using this library is pretty straightforward, just import the -- Orchestrate module like this: -- -- 
--   import qualified Orchestrate as DB
--
-- -- Once you have it, you can use all the supported API functions(Check -- out the documentation on REST for detailed information). One -- important thing you need to remeber when working with this library is, -- that it uses Aeson under the hood, so if you want to store your -- Haskell types in an Orchestrate database, Aseon must know how -- convert them into JSON. The best way to achive that, is to use the -- DeriveGeneric Langauge extension. -- -- Here is an example of how to store a haskell value in an Orchestrate -- Collection: -- -- 
--   {-# LANGUAGE DeriveGeneric     #-}
--   module Main where
--   
--   import GHC.Generics
--   import Data.Aeson
--   import qualified Database.Orchestrate as DB
--   
--   data SherlockHolmesCase = SherlockHolmesCase {
--     title :: String,
--     typeOfCrime :: String,
--     shortStory :: Bool,
--     index :: Integer,
--     solved :: Bool
--   } deriving (Show,Read,Generic,Eq)
--   
--   {-This automatically creates both a JSON parser and a JSON encoder based on the data type SherlockHolmesCase, if you however
--   want the property names in JSON and haskell to differ, you will have to write your own parser and you own encoder.
--    Please check out the Aeson documentation for information on how to do that.-}
--   instance FromJSON SherlockHolmesCase
--   instance ToJSON SherlockHolmesCase
--   
--   main :: IO ()
--   main = do
--     -- Create an application record. Oh, BTW, in case you planned to store your api-key in the source code, it is a very very bad idea.
--     let dbApplcation = DB.createStdApplication "your.orchestrate.application.name" "one-of-your-api-keys"
--     -- Create an collection record. This collection does not have to exist, if it does not, it will be created as soon as you try to store something in it.
--     let dbCollection = DB.createStdCollection "TheCasebookOfSherlockHolmes"
--     let aStudyInScarlet = SherlockHolmesCase {
--       title = "A Study in Scarlet",
--       typeOfCrime = "Murder",
--       shortStory = False,
--       index = 0,
--       solved = True
--     }
--     -- Store a haskell value in the collection we created earlier. The "withOutKey" lets the server generate the key, so no key must be specified.
--     didItWork <- DB.orchestrateCollectionPutWithoutKey dbApplcation dbCollection aStudyInScarlet
--     if didItWork
--       then putStrLn "Invictus maneo!"
--       else putStrLn "Something is rotten in the state of Denmark!"
--
-- -- If this application does say "Invictus maneo!", you should get this -- result if you LIST the "TheCasebookOfSherlockHolmes" collection: -- -- 
--   "count" : 1,
--     "results" : [ {
--       "path" : {
--         "collection" : "TheCasebookOfSherlockHolmes ",
--         "kind" : "item",
--         "key" : "0b8b506cf0204ce9",
--         "ref" : "--------------",
--         "reftime" : --------------
--       },
--       "value" : {
--         "solved" : true,
--         "shortStory" : false,
--         "title" : "A Study in Scarlet ",
--         "index" : 0,
--         "typeOfCrime" : "Murder "
--       },
--       "reftime" : --------------
--     } ]
--
-- -- If you don't get that result, you either have run the example more -- than once, it did not return "Invictus maneo", or something really -- strange is going on. If you are fairly certain, that something strange -- is going on, and it is most likely my fault and you might want to open -- an issue at github. -- --

How to use the "cabal test" command

-- -- Testing applications which depend on some REST api is not easy, and -- therfore the cabal tests will fail by default. They just will not be -- able to authenticate, if you want to run the tests on your local -- machine, please create a file called "examples/config.txt" and fill it -- according to this scheme: -- -- 
--   ("a valid api key","something funny(it will be used as a name for the test collection)")
--
-- -- If you are asking yourself now, if there really is no way of checking -- that this library works, before installing it, there is nothing to -- worry about. You should consult the travis-ci -- server(https://travis-ci.org/dwd31415/Haskell-OrchestrateDB) on -- the state of the project, it does not only check wether or not ther -- library can be built, but also runs the tests with an valid api key. module Database.Orchestrate -- | Represents a collection inside an OrchestrateApplication, it stores -- all data necessary to access it. data OrchestrateCollection OrchestrateCollection :: String -> OrchestrateCollection collectionName :: OrchestrateCollection -> String -- | A data type, that represents an Orchestrate application. It stores an -- api key (generated online) and a https-endpoint. data OrchestrateApplication OrchestrateApplication :: String -> String -> String -> OrchestrateApplication applicationName :: OrchestrateApplication -> String apiKey :: OrchestrateApplication -> String httpsEndpoint :: OrchestrateApplication -> String -- | The validateApplication function validates your API key, by -- making an authenticated HEAD request to the endpoint specified in the -- OrchestrateApplication record. The function returns False when -- the key is invalid or no connection with the endpoint could be -- established. validateApplication :: OrchestrateApplication -> IO Bool -- | The orchestrateCollectionGet function request a value from an -- Orchestrate.io database, and tries to convert it to the specified -- Haskell type, if either gettings the value from the database or -- converting it to the Haskell type fails Nothing is returned. -- The value is requested by making a GET request to the -- /$collection/$key endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#keyvalue-get) -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   dbValue <- DB.orchestrateCollectionGet dbApplication dbCollection KEY :: IO (Maybe TestRecord)
--   
--
orchestrateCollectionGet :: FromJSON res => OrchestrateApplication -> OrchestrateCollection -> String -> IO (Maybe res) -- | The orchestrateCollectionPut function stores a Haskell -- value(with a ToJSON instance) in an Orchestrate.io database. It -- does so by making a PUT request to the /$collection/$key -- endpoint(Offical API -- docs:https://orchestrate.io/docs/apiref#keyvalue-put). In order -- to upload a Haskell Value to the database, it must have an instance of -- ToJSON because this client library uses Aeson to convert -- Haskel Values to JSON, which is required by Orchestrate.io. -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   _ <- DB.orchestrateCollectionPutWithoutKey dbApplication dbCollection KEY testRecord
--   
--
orchestrateCollectionPut :: ToJSON obj => OrchestrateApplication -> OrchestrateCollection -> String -> obj -> IO Bool -- | The orchestrateCollectionPutWithoutKey function stores a -- Haskell value(with a ToJSON instance) in an Orchestrate.io -- database. It does so by making a POST request to the /$collection -- endpoint(Offical API -- docs:https://orchestrate.io/docs/apiref#keyvalue-post). This -- function does not need a user specified key, because it uses a -- server-generated key, if you want to know the key use -- orchestrateCollectionPut instead of this function. -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let testRecord = TestRecord {string = "You may delay, but time will not!",number = 903}
--   _ <- DB.orchestrateCollectionPutWithoutKey dbApplication dbCollection testRecord
--   
--
orchestrateCollectionPutWithoutKey :: ToJSON obj => OrchestrateApplication -> OrchestrateCollection -> obj -> IO Bool -- | The orchestrateCollectionDelete function deletes a collection -- from an Orchestrate.io application. This is done by making a DELETE -- request to the /$collection endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#collections-delete) -- --

Example:

-- -- 
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   _ <- DB.orchestrateCollectionDelete dbApplication dbCollection
--   
--
orchestrateCollectionDelete :: OrchestrateApplication -> OrchestrateCollection -> IO Bool -- | The orchestrateCollectionDeleteKey function deletes a value -- from an Orchestrate.io database. This is done by making a DELETE -- request to the /$collection/$key endpoint(Offical -- documentation:https://orchestrate.io/docs/apiref#keyvalue-delete) -- --

Example:

-- -- 
--   data TestRecord = TestRecord
--     { string :: String
--      , number :: Int
--     } deriving (Show,Read,Generic,Eq)
--   
--   instance FromJSON TestRecord
--   instance ToJSON TestRecord
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   _ <- DB.orchestrateCollectionKey dbApplication dbCollection KEY
--   
--
orchestrateCollectionDeleteKey :: OrchestrateApplication -> OrchestrateCollection -> String -> IO Bool -- | Please see orchestrateCollectionSearchWithOffset for more -- information. This function just calls it without an offset and with a -- limit of 10. orchestrateCollectionSearch :: OrchestrateApplication -> OrchestrateCollection -> String -> IO (Maybe ([Object], Bool)) -- | The orchestrateCollectionSearchWithOffset function searches for -- the query in the database and returns an array of the type -- "Maybe [Object]". Nothing is returned when establishing -- a connection or authenticating failed. The function uses the SEARCH -- method of the Orchestrate.io API (Offical -- documentation:https://orchestrate.io/docs/apiref#search-collection) -- , but automatically parsers the response. It returns a tupel of the -- type (Maybe([Object],Bool)), the boolean -- indicates wether or not more results are availble on the server. If -- that is true, the function should be called again with an increased -- offset, until (Just _,False) is returned. -- --

Example:

-- -- 
--   dbSearchResults query num =
--       let results = DB.orchestrateCollectionSearchWithOffset query num (num+10)
--       let currentResults = fromJust $ fst results
--       if snd results
--          then currentResults:(dbSearchResults query (num+10))
--          else currentResults
--   
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   let completeDBSearchResults = dbSearchResults QUERY 0
--   
--
orchestrateCollectionSearchWithOffset :: OrchestrateApplication -> OrchestrateCollection -> String -> Integer -> Integer -> IO (Maybe ([Object], Bool)) -- | The orchestrateCollectionList function lists the contents of -- the specified collection, by making GET request to the -- /$collection?limit=$limit endpoint. For more information check out the -- Orchestrate.io API docs: -- https://orchestrate.io/docs/apiref#keyvalue-list. If connecting -- to the api fails, or the api key stored in the application record is -- invlaid, Nothing is returned. Otherwise an array of the type -- Object(see the documentation of Aeson for more -- information) is returned, it contains the values from the HTTP -- response(see https://orchestrate.io/docs/apiref#keyvalue-list -- for an example of how the response looks like in JSON). -- --

Example:

-- -- 
--   let dbApplication = DB.createStdApplication "APPLICATION_NAME" "API_KEY"
--   let dbCollection = DB.createStdCollection "COLLECTION_NAME"
--   dbContents <- DB.orchestrateCollectionList dbApplication dbCollection 10
--   
--
orchestrateCollectionList :: OrchestrateApplication -> OrchestrateCollection -> Integer -> IO (Maybe [Object]) -- | Creates an collection record. createStdCollection :: String -> OrchestrateCollection -- | Creates an application record with the -- std.("https:/api.orchestrate.iov0") enpoint. createStdApplication :: String -> String -> OrchestrateApplication