USA Web Child State

The USA Web Child State API is a RESTful API.

The service is used to check the availability of a single child as well as marking a child as locked to a particular user or sponsor.

GET requests are used for checking a child’s state. PUT requests are used for updating a child’s state. The response from either a GET or PUT is the child’s current lock state. HTTP status codes are used to communicate whether the child is available or not.

Sample Requests

https://webapi.compassion.com/children/BR1231234/state?sessionId=[guid]&api_key=[string]
https://webapi.compassion.com/children/BR1231234/state.json?sessionId=[guid]&api_key=[string]

Sample PUT Request Bodies

When performing a PUT request, be certain to set the Content-Type header to the appropriate value: either application/json or application/xml. A PUT request is intended to be idempotent – making the same request multiple times results in the same state for the item. Certain facets of the service are idempotent, but because of the nature of locking/sponsoring there will always be situations where the response will change (another user has locked/sponsored the child, etc).

Possible states for PUT requests:

StateAction requested
L Lock
A Unlock
S Sponsor
U Unsponsor

Lock

When locking a child, the “lockMinutes” value indicates how long the lock on the child should last. 60 minutes is the default value if no “lockMinutes” is supplied. A maximum value of 120 minutes is currently allowed, although depending on needs this could be raised to allow a child to be locked for an event or similar activity.

{
    "state": "L",
    "lockMinutes": 15
}

Unlock

This PUT request will unlock the child specified in the URI if the sessionId in the querystring matches the session ID that has the child locked.

{
    "state": "A"
}

Sponsor

If the child is Available or locked to the user specified in the sessionId parameter, the child will be marked as Sponsored and be unavailable to the available children searches/services.

{
    "state": "S"
}

Un-Sponsor

A child will be unsponsored if the user specified in the sessionId parameter was the user that marked the child sponsored and is executing the request within 60 seconds of the original sponsorship. This is a short window to allow for additional checks to reverse the sponsorship, but once the child is marked sponsored for more than 60 seconds there are other processes that would be problematic to reverse.

{
    "state": "U"
}

Example of an application/xml request body:

<LockState>
    <State>L</State>
    <LockMinutes>20</LockMinutes>
</LockState>

Request Parameters

NameDescriptionRequiredData TypeConstraints
ChildKey URI Parameter. The child key is part of the resource URI.
Yes String Format: [a-zA-Z]{2}/d{7}
sessionId Querystring Parameter. This is a client-specific identifier used to ensure only one user can lock/sponsor a child. Yes GUID
api_key Querystring Parameter. Mashery-supplied key for accessing Compassion International services Yes String

Specifying Format

By default, all requests will be returned as JSON. There are two ways to indicate an explicit format – either by using an extension on the endpoint (.json or .xml) or by setting the Accept header in the initial request (“application/json” or “application/xml”).

PUT Requests

When attempting to perform an update.

Sample Responses

Possible State Responses:

StateDefinition
A Available
L Locked
S Sponsored
N Unavailable
X Error

JSON (GET:/children/BR1231234/state.json)

{
    "state":"A",
    "stateDefinition":"Available"
}

JSON (PUT:/children/BR1231234/state.json)

{
    "state":"L",
    "stateDefinition":"Locked",
    "message":"Completed"
}

XML (GET:/children/BR1231234/state.xml)

<LockState>
    <State>A</State>
    <StateDefinition>Available</StateDefinition>
</LockState>

XML (PUT:/children/BR1231234/state.xml)

<LockState>
    <State>L</State>
    <StateDefinition>Locked</StateDefinition>
    <Message>Completed</StateDefinition>
</LockState>

PUT Requests: Possible Status Codes and Responses


AvailableLocked by UserLocked by AnotherSponsored by UserSponsored by AnotherNot in Web Pool
PUT
Lock (L)

200: OK
L: Locked
Completed

200 - OK
L: Locked
Completed

409: Conflict
L: Locked
Locked by another person

410: Gone
S: Sponsored
Sponsored by another person

410: Gone
S: Sponsored
Sponsored by another person

404: NotFound
N: Unavailable
Child is not in the pool of available children

PUT
Unlock (A)

200: OK
A: Available
Completed

200: OK
A: Available
Completed



PUT
Sponsor (S)

200: OK
S: Sponsored
Completed

200: OK
S: Sponsored
Completed

200: OK
S: Sponsored
Completed

PUT
Unsponsor (U)

200: OK
A: Available
Completed

200: OK
L: Locked
Completed

if within 60s & lock expiration still valid:

200: OK

L: Locked

Completed

 

if within 60s & lock expiration invalid:

200: OK

A: Available

Completed

 

After 60s:

410: Gone

S: Sponsored

Sponsored by another person

Docs Navigation