Skip to content

API.md

Latest commit

 

History

History
173 lines (142 loc) · 14.5 KB

API.md

File metadata and controls

173 lines (142 loc) · 14.5 KB
Raw

The Basics

At the heart of the ActiveStack API are SyncRequest's and SyncResponse's. A specialized SyncRequest is sent to the ActiveStack Sync Engine and a SyncResponse is sent back the two being linked together by the SyncResponse.correspondingMessageId, which is the ID of the SyncRequest.

Login

Login is perhaps the most complicated of the API's in that it is meant to be generic and flexible enough to handle any type of authentication (OAuth, username/password, custom, etc). The main authentication engine is AuthService2.

Login basically accepts some form of user credentials and returns a UserID and ClientID upon successful authentication. The ClientID is the main way that ActiveStack knows who the user is and also enables a single user to be simultaneously logged in on multipled devices.

A successful login returns a UserToken object that contains the User, clientId, deviceId, and token (required for reauthentication). Typically, upon successful login, the app will issue a findByExample request for the class that represents the user in the application. For example, if Person is the class that represents the user, the app would issue a findByExample request with theObject payload:

{
  "cn": "com.app.mo.Person",  // Or whatever the actual class name of the `Person` object is
  "userId": <UserToken.User.ID>,  // The `UserToken`.`User`.`ID` from the `AuthenticationResponse`
}

This should result in the Person object identified by that User.ID to be returned by the ActiveStack SyncEngine.

register

authenticate

reauthenticate

  • Reauthenticates a user by a token (which is typically assigned upon successful authentication).
    • Request: ReauthenticationRequest
    • Response: AuthenticationResponse
    • Parameters:
      • authProvider: This is the name of the auth provider that will be used for authentication. The auth provider can either be built-in auth providers, or a custom defined auth provider.
      • token: This is the string token that was returned upon successful authentication.

disconnect SyncEngine

  • Disconnects a client from the ActiveStack SyncEngine. This means that the client will no longer be pushed updates. Note that updates will be stored up for the client until they either reconnect or logout.

disconnect Auth

logout

  • Logs out a client from ActiveStack. This means that the client will no longer be notified of updates. Note that updates will NOT be stored up for the client.
    • Request: LogoutRequest
    • Response: null - Since the client has logged out, it is assumed they are not listening for any further messages, so no response is sent.
    • Parameters:
      • userId
      • clientId

Core API

  • All className references assume that the corresponding class is part of the registered data model, meaning it is included in the ActiveStack.Domain module.

connect

  • Upon successful authentication, the ActiveStack Gateway will send a ConnectRequest to the SyncEngine on behalf of the client. This is to let the SyncEngine know that this client has come online.
  • NOTE: The client app itself is never aware of this ConnectRequest, it is handled automatically under the hood by the ActiveStack Gateway. However, the ConnectResponse IS sent to the client app so that it knows it is now connected to the SyncEngine and can start sending requests.

reconnect

findById

  • Retrieves the object identified by a className and an ID. The server will respond with a findByIdResponse containing either the result, or a NULL result indicating the specified object was not found, and registers the Client for any updates to that object.
    • Request: FindByIdRequest
    • Response: FindByIdResponse
    • Parameters:
      • theClassName: The name of the class
      • theClassId: The ID of the object to find
    • Note that the API should be able to handle inheritance. So "parentClass::ID" and "class::ID" should both return the same result (assuming that "class" inherits from "parentClass").

findByIds

  • Retrieves a list of object identified by the className and a list of ID's and registers the Client for any updates to those objects.
    • Request: FindByIdsRequest
    • Response: FindByIdsResponse
    • Parameters:
      • theClassIdList: ClassIDPairs object which contains the className and a list of ID's to retrieve
    • Note that the API should be able to handle inheritance. So "parentClass::ID" and "class::ID" should both return the same result (assuming that "class" inherits from "parentClass").

getAllByName

  • Retrieves all objects of a particular class and registers the Client for any updates to those objects.
    • Request: GetAllByNameRequest
    • Response: GetAllByNameResponse
    • Parameters:
      • theClassName: The name of the class to get all objects.
      • pageSize (optional): Number of items to return in result.
      • pageNumber (optional): Desired page number
      • returnTotal (optional): If set to true, returns the total number of objects to be returned. Typically used in the first call to determine exactly how many objects are expected.

findByExample

  • Retrieves all objects that match the supplied sample object and registers the Client for any updates to those objects.
    • Request: FindByExampleRequest
    • Response: FindByExampleResponse
    • Parameters:
      • theObject: A sample object of the domain model. Fields on the object that are set will be included as part of the filter criteria

putObject

  • Updates an existing object
    • Request: PutRequest
    • Response: PutResponse
    • Parameters:
      • theObject
      • putTimestamp (optional): The time this object was updated. This is used for conflict resolution
      • transId (optional): A client defined transaction ID. Mostly used for tracking of updates, does NOT enforce a database transaction.

createObject

  • Creates a new object
    • Request: CreateRequest
    • Response: CreateResponse
    • Parameters:
      • theObject: The object to be created. If the object does NOT contain an ID, the ActiveStack Sync Engine will create one.

removeObject

getChangeWatcher

  • Retrieves the value of a ChangeWatcher and registers the Client for any updates to that value.
    • Request: PushCWUpdateRequest
    • Response: PushCWUpdateResponse
    • Parameters:
      • classIdPair: A ClassIDPair identifying the ID and class name of the object that the ChangeWatcher hangs off of.
      • fieldName: The name of the field that represents the ChangeWatcher.
      • params (optional): An array of strings that represent the parameters that uniquely identify the ChangeWatcher.

runServerProcess

  • Runs a custom server process. This process can be a custom piece of code, a defined HTTP process, a defined SQL stored procedure, or some other defined Connector.
    • Request: RunServerProcessRequest
    • Response: RunServerProcessResponse
    • Parameters:
      • queryName: The name of the process. To use a specific Connector (such as 'HTTP' or 'SQL_PROC' for database stored procedures), prefix the operation name of the Connector name and a ":". Example: "HTTP:fetchDataFromHttpEndpoint"
      • queryArguments (optional): Any required parameters for the server process. Typically, this is passed as some sort of map (parameterName -> parameterValue)

Push Notifications from SyncEngine

This is really where the real-time aspect of ActiveStack comes into play. The main point here is that clients are notified of updates to objects that they are currently interested in. It is up to the client SDK to respond appropriately to these update notifications.

pushUpdate

Sent whenever an object has been updated for which a client has registered to receive updates.

deleteUpdate

Sent whenever an object has been deleted for which a client has registered to receive updates.