API

The API (Application Programming Interface) consists of a set of methods each of which are formed in the body of an HTTP request. The applicable URL contains the IP address of the machine that ARCS is installed on as well as and your specific ApplicationID, e.g. http://192.44.11.181:8080/MyApp. (The ApplicationID is specified during Setup.)
The URL is case-insensitive.

The basic idea is that you begin an ARCS session on behalf of some user of your application. You then bind some specified resource for that user, the user somehow utilizes the resource in your application for some period of time, and then you release the resource when finished. While the resource is bound, it cannot be bound by any other user (unless you specify some Capacity greater than 1 for, e.g. user counting). However, when applicable (see Threshold below), the resource can be bound by some other user if the original user hasn't checked-in "recently". Applications do indeed crash and when such is the case, the user should not be allowed to continue binding some resource if another user does actually try to bind that same resource. Keep in mind that a resource may be any abstract thing. To ARCS, it is simply an identifier for something that it aptly "protects".

The following table lists all of the method calls and all possible arguments.
Where X is placed, the argument is required; where {X} is placed, the argument is optional. All method names, argument names, and argument values are case-sensitive.

Arguments ------------------- Method	UserID	ResourceID	Threshold	Capacity
Begin	X		{X}
Bind	X	X		{X}
Release	X	X
CheckIn	X
Info	{X}	{X}
End	X

Arguments

The arguments are described before the methods because the descriptions of the methods make more sense after knowing what all of the arguments mean.

UserID (string)
Identifier of the user.
This is a competitor/owner of resources that are encapsulated by a particular ApplicationID.

ResourceID (string)
Identifier of the resource.

Threshold (non-negative integer or float)
This is the amount of time, in seconds, that, if surpassed, the user is susceptible to being wiped out, since it may be assumed that the user's application has crashed. The user is not a candidate for being wiped out until an applicable resource slot is needed or a user slot beyond the maximum is needed.
Default: 0 --> The user cannot be wiped out.

Capacity (integer)
Maximum number of users allowed to bind/own the resource.
Setting this to a value greater than 1 is useful for, e.g. user license counting.
Setting this to 0 means there is no constraint on the usage of the resource (good for basic feature tracking).
Setting this to a value less than 0 imposes that capacity (its absolute value) on all other calls too.
Default: 1 --> exclusive access

Methods

Begin - Begin a new session for some user.

Arguments: UserID, {Threshold}

Result:

1	Success.
0	The ARCS user-limit had already been reached (need an ApplicationID license to get a higher user-limit).

Bind - Bind a resource for some user.

Arguments: UserID, ResourceID, {Capacity}, {Data}

Result:

Success.

If the resource was already bound by the passed user, its update-timestamp was simply updated.

The resource could not be bound because it is already being used at full capacity.

-1

The passed UserID does not exist.

Release - Release a resource for some user.

Arguments: UserID, ResourceID

Result:

1	Success (was bound by the passed user and is now released).
0	The resource was not bound by the passed user or by anybody else.
-1	The passed UserID does not exist.

CheckIn - Check-in with the server and update the activity-timestamp for the passed user. All other methods update the activity-timestamp as well. This method is typically called on a timer (in your application) having an interval that is less than or equal to the threshold passed to Begin. Basically, it is called to show that the user's application hasn't crashed; this is intended to ensure that the user session is not wiped out upon some other user attempting to bind a resource this user has bound. A server hosting multiple users, e.g. a web server, may call CheckIn on behalf of its users when such users check-in with it.

Arguments: UserID

Result:

1	Success. The activity-timestamp was updated.
-1	The passed UserID does not exist.

Info - Retrieve information about some user and the resources for that user.

Arguments: {UserID}, {ResourceID}

If no UserID is passed or it is passed as an empty string, it is implied to be all of the current users.

If no ResourceID is passed or it is passed as an empty string, it is implied to be all of the current resources.

Result: There are three elements in the result.

[1]

Current timestamp of the system.
This may be compared to your own timestamp or to the timestamps returned in the 2nd and 3rd elements below (the client may be in a different time zone than the server).
(See the section “Timestamps:” for the format.)

[2]

This element contains information for each user that satisfies all of the following criteria:

Matches the UserID passed
Is binding the ResourceID passed

Its exact structure varies by protocol but it is abstractly defined as rows and columns of a table. There is one row per user and the columns are as follows:

UserID, InitialTimestamp, ActivityTimestamp, Threshold.

[3]

This element contains information for each resource that satisfies all of the following criteria:

Matches the ResourceID passed
Is bound by the UserID passed

Its exact structure varies by protocol but it is abstractly defined as rows and columns of a table. There is one row per resource and the columns are as follows:

UserID, ResourceID, InitialTimestamp, UpdateTimestamp, Capacity, Data.

End - End the session for some user.

Arguments: UserID

Result:

1	Success. All of the user's bindings on resources were released.
-1	The passed UserID does not exist.

Example - Sequence of Steps

The following table exemplifies a typical simple sequence of steps.
Where a cell contains Request or Response, it is to be understood that the respective content is for the body of the HTTP sent or received.
In this example, the resource referred to as MyUserLicense, is meant to be your application's idea of a user-license; it is not referring to user licensing with regard to ARCS itself.

Request:
Begin
MyUserA
600

Response:
1

Request:
Bind
MyUserA
MyUserLicense
20

Response:
1

Miscellaneous application activity...

4) [Probably called several times throughout the user session, on a timer]

Request:
CheckIn
MyUserA

Response:
1

Request:
Bind
MyUserA
MyResourceN

Response:
1

Edit MyResourceN...

Request:
Release
MyUserA
MyResourceN

Response:
1

Miscellaneous application activity...

9) [This step is optional since all resources will be released when End is
called in the next step.]

Request:
Release
MyUserA
MyUserLicense

Response:
1

10)

Request:
End
MyUserA

Response:
1

Protocols

There are 3 different protocols that can be used in the requests/responses in the HTTP body. They all have the same breadth of functionality and behavior. Use the one that is most convenient for you. Contact info@arcs.us if you have a need for a reasonable protocol that is not listed below.

1) Basic (note: The example above was written using the Basic protocol.)
Use the following HTTP content-type: text/plain

[Request]:
Each line should be separated by the following two characters: carriage-return, line-feed (or either one of them singly). The first line contains the method name. All subsequent lines contain the arguments to the method, in the order specified by the Methods/Arguments table at the top of this section. Optional arguments can simply be omitted since they are, by design, at the end.

[Response]:
For all methods except for Info, the numeric result is on a single line (see the detailed explanation for Info at the end of this section).

2) SOAP
Use the following HTTP content-type: text/xml

[Request]:
The request is a standard SOAP wrapper and body. Below is an example using the method Begin. Other methods have an analogous format in that the names of the elements follow the argument names in the Methods/Arguments table at the top of this section.

<?xml version="1.0"?> <SOAP-ENV:Envelope SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Body>
<Begin>
<UserID>MyUserA</UserID>
<Threshold>600</Threshold>
</Begin>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

[Response]:
<?xml version="1.0"?><SOAP-ENV:Envelope …<SOAP-ENV:Body>
<BeginResponse><Success>1</Success></BeginResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

3) FormPost
Use the following HTTP content-type: application/x-www-form-urlencoded

[Request]:
The request is encoded as name/value pairs (as specified for the HTTP content-type above). Below is an example using the method Begin. Other methods have an analogous format in that the names of the elements follow the argument names in the Methods/Arguments table at the top of this section.

Method=Begin&UserID=MyUserA&Threshold=600

[Response]:
1

Timestamps:

For all of the protocols, timestamps are of the following format, consisting of 23 characters:
ccyy-mm-ddThh:mm:ss.sss
Example: 2006-02-19T20:34:41.434
This is a valid format of the XML Schema “dateTime” primitive datatype.

More on the Info method

It may be helpful to refer to the description of the result of Info under the section Methods.

Applicable to the Basic and FormPost protocols: The result elements (the three elements that are described above under Methods) are delimited from each other by two sets of carriage-return/line-feed (4 characters in total). The second and third elements each delimit their respective rows with carriage-return/line-feed and delimit their respective columns with a tab character. It is recommended that you try it out for yourself to see how the result looks.

The SOAP protocol can be understood by following the example below (the SOAP wrapper is omitted there, for clarity).

Example - Info method using the SOAP protocol:

[Request]:
<Info> 
<UserID>MyUserA</UserID>
<ResourceID></ResourceID>
</Info>

[Response]:
<InfoResponse>
<SystemTimestamp>2006-02-19T34:24:21.534</SystemTimestamp>
<Users>
<User>
<UserID>MyUserA</UserID>
<InitialTimestamp>
2006-02-19T20:34:41.434
</InitialTimestamp>
<ActivityTimestamp>
2006-02-19T30:34:51.531
</ActivityTimestamp>
<Threshold>600</Threshold>
</User>
</Users>
<Resources>
<Resource>
<UserID>MyUserA</UserID>
<ResourceID>MyUserLicense</ResourceID>
<InitialTimestamp>
2006-02-19T20:35:02.357
</InitialTimestamp>
<UpdateTimestamp>
2006-02-19T20:35:02.357
</UpdateTimestamp>
<Capacity>10</Capacity>
<Data>whatever you want</Data>
</Resource>
<Resource>
<UserID>MyUserA</UserID>
<ResourceID>MyResourceN</ResourceID>
<InitialTimestamp>
2006-02-19T23:53:21.333
</InitialTimestamp>
<UpdateTimestamp>
2006-02-19T23:53:21.333
</UpdateTimestamp>
<Capacity>1</Capacity>
<Data>...</Data>
</Resource>
</Resources>
</InfoResponse>

Example - Simplified Code

You should be able to copy/paste the following pseudo-code and make the necessary adjustments to get something working very quickly.

url = "http://192.44.11.181:8080/MyApp"
http = new ActiveXObject("Microsoft.XMLHTTP")

user = "UserA"
threshold = 600
request = "Begin" + "\n" + user + "\n" + threshold

http.open("POST", url, false)
http.setRequestHeader("Content-Type", "text/plain")
http.send(request)
response = http.responseText // you should then check on the success of this result

request = "Bind" + "\n" + user + "\n" + "MyResourceN"
http.open("POST", url, false)
http.setRequestHeader("Content-Type", "text/plain")
http.send(request)
response = http.responseText // you should then check on the success of this result

Web design by Helen Lee

OVERVIEW

INSTALLATION

EVALUATION

PURCHASE

SUPPORT

API

USAGE

MONITORING

API

Arguments

Methods

Example - Sequence of Steps

Protocols

Timestamps:

More on the Info method

Example - Simplified Code