- Previous: USA Web Children Search
- Up: Private USA Web APIs
- Next: Sample REST End-To-End Test Plan
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:
State | Action 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
Name | Description | Required | Data Type | Constraints |
---|---|---|---|---|
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:
State | Definition |
---|---|
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
Available | Locked by User | Locked by Another | Sponsored by User | Sponsored by Another | Not in Web Pool | |
---|---|---|---|---|---|---|
PUT Lock (L) |
200: OK |
200 - OK |
409: Conflict |
410: Gone |
410: Gone |
404: NotFound |
PUT Unlock (A) |
200: OK |
200: OK |
“ |
“ |
“ | “ |
PUT Sponsor (S) |
200: OK |
200: OK |
“ |
200: OK |
“ | “ |
PUT Unsponsor (U) |
200: OK |
200: OK |
“ |
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 |
“ | “ |
- Previous: USA Web Children Search
- Up: Private USA Web APIs
- Next: Sample REST End-To-End Test Plan
Docs Navigation
- Compassion API Library
- Standards Documents
- Legacy APIs (Deprecating)
- Web Services Handshake (Legacy) - Notification and Command Messages
- Public API
- Private IPG APIs
- Private REST Services
- REST Get CDSP Implementor V1
- REST Get Child Case Study V1
- REST Get Child Exit Details V1
- REST Get Child Image V1
- REST Get Child Information V1
- REST Get Community V1
- REST Get Country V1
- REST Get CSP Implementor V1
- REST Get Local Church Partner V1
- REST Get Program Implementor V1
- REST Get Project Age Groups V1
- REST Get Child Image V1 - 2015/03
- Private Messaging APIs
- Quick Start Guide
- OffRamp Prerequisites and Setup
- IP OnRamp Service Configuration
- Available Message Types
- Message and Service Relationships
- Troubleshooting
- General Error Messages from Compass Party Host
- EsdMessageErrorMOE Sample
- Sample REST End-To-End Test Plan
- SOAP Wrapper Sample for Messages to GMC
- Allocate Child Message
- Cancel Commitment Message
- Commitment Canceled Message
- Commitment Created Message
- Constituent Created Message
- Constituent Updated Message
- Constituent Upserted Message
- Create Commitment Message
- Create Constituent Message
- Create Email Message
- Create Gift Message
- Deallocate Child Message
- Depart Child Message
- Email Created Message
- Email Updated Message
- Gift Created Message
- Update Child Message
- Update Constituent Message
- Update Email Message
- Upsert Constituent Message
- Update Project Message
- Private SOAP Services
- SOAP Get Child Exit Detail 201211
- SOAP Get Child Exit Detail 201310
- SOAP Get CDSP Implementor 201309
- SOAP Get Child Image 201211
- SOAP Get Child Case Study 201310
- SOAP Get Child Case Study 201412
- SOAP Get Child Information 201211
- SOAP Get Child Information 201310
- SOAP Get Community 201309
- SOAP Get Country Information 201104
- SOAP Get Local Church Partner 201309
- SOAP Get Program Implementor 201303
- SOAP Get Program Implementor 201309
- SOAP Get Project Age Group 201309
- Service Overview
- SOAP Get CSP Implementor 201309
- SOAP Get Child Image 201503
- Private USA APIs
- Private USA Web APIs
- private cornerstone connect messaging
- private cornerstone test
- public api
0 Comments
New comments are not being accepted at this time.