Draft of what the Crisis Checkin Web API for mobile apps might be

CrisisCheckin-WebAPI.md

Here is a proposal for a web api for the Crisis Checkin app which the mobile apps will call.

General Notes about the API

The API should send and receive JSON data.

The Base Url should be /api/

All responses should include one of the following http response status codes:

• 200 - OK
• 403 - Authentication Failed (Auth Token bad)
• 5xx - Some server side error (should send accompanying JSON payload with Success=true and Error="Some Message")

If there is any error to return at all, the response json should include:

{
	"Success" : true,
	"Error" : "User friendly error message"
}	

API Methods

Register

Url: /api/register

Parameters:

• string FirstName
• string LastName
• string Email
• string Password
• int ClusterId - User selects from a list of Cluster's at registration screen

Sample Request:

{ 
	"FirstName" : "John",
	"LastName" : "Smith",
	"Username" : "john.smith",
	"Email" : "[email protected]",
	"Password" : "1234John!@",
	"ClusterId" : 3
}

Sample Response:

{
	"Success" : true,
	"Result" : "john.smith"
}

---

Signin

Url: /api/signin

Parameters:

• string Email - Could be email or username
• string Password

Sample Request:

{
	"Email" : "[email protected]",
	"Password" : "1234John!@"
}

Sample Response:

{
	"Success" : true,
	"Result" : "john.smith"
}

---

Signout

Signout may not really be explicitly needed, but let's assume it is for now.

Url: /api/signout

Parameters:

• string AuthToken - For now this is the user's username

Sample Request:

{
	"AuthToken" : "john.smith"
}

Sample Response:

{
	"Success" : true
}

---

Clusters

Url: /api/clusters

Parameters:

• string AuthToken - For now this is the user's username

Sample Request:

{
	"AuthToken" : "john.smith"
}

Sample Response:

The response result will be of type IEnumerable<Cluster>

{
	"Success" : true,
	"Result" : [
		{ "Id" : 7, "Name" : "Health Cluster" },
		{ "Id" : 8, "Name" : "Logistics Cluster" }
	]
}

---

Disasters

For obtaining a list of disasters to volunteer for. This list should be sorted by proximity to the given longitude / latitude if they are provided (closest to furthest).

Url: /api/disasters

Parameters:

• string AuthToken - For now this is the user's username
• double Latitude - optional
• double Longitude - optional

Sample Request:

Longitude/Latitude are optional, but if specified should be the location from the client device.

{
	"AuthToken" : "john.smith",
	"Latitude" : -23.1234,
	"Longitude" : 44.1234
}

Sample Response:

Result will be of type IEnumerable<Disaster>

{
	"Success" : true,
	"Result" : [
		{ 
			"Id" : 1, 
			"IsActive" : true,
			"Name" : "Earthquake",
			"Location" : "Panguna, Papa New Guinea" 
		},
		{ 
			"Id" : 2,
			"IsActive" : true,
			"Name" : "Tsunami",
			"Location" : "Ao Nang, Thailand" 
		}
	]
}

---

Volunteer

This is called when a user commits themselves to volunteer at a given disaster. Dates should in an acceptable JSON date format.

Url: /api/volunteer

Parameters:

• string AuthToken - For now this is the user's username
• int DisasterId
• DateTime StartDate
• DateTime EndDate

Sample Request:

{
	"AuthToken" : "john.smith",
	"DisasterId" : 2,
	"StartDate" : "2015-01-01",
	"EndDate" : "2015-02-01"
}

Sample Response:

{
	"Success" : true
}

---

Commitments

Gets a list of all commitments a user is part of or was part of.

Url: /api/commitments

Parameters:

• string AuthToken - For now this is the user's username

Sample Request:

{
	"AuthToken" : "john.smith"
}

Sample Response:

Result will be of type IEnumerable<Commitment>

{
	"Success" : true,
	"Result" : [
		{
			"DisasterId" = 1,
			"IsActive" = true,
			"StartDate" = "2015-01-01",
			"EndDate" = "2015-02-01",
			"Disaster" = {
				"Id" : 1, 
				"IsActive" : true,
				"Name" : "Earthquake",
				"Location" : "Panguna, Papa New Guinea" 
			}
		},
		{
			"DisasterId" = 2,
			"IsActive" = false,
			"StartDate" = "2015-03-01",
			"EndDate" = "2015-04-01",
			"Disaster" = {
				"Id" : 2,
				"IsActive" : true,
				"Name" : "Tsunami",
				"Location" : "Ao Nang, Thailand"
			}
		}
	]
}

---

CheckIn

Url: /api/checkin

Parameters:

• string AuthToken - For now this is the user's username
• int DisasterId
• double Latitude
• double Longitude

Sample Request:

Longitude / Latitude should be sent if at all possible, not sure if this is required, but maybe should be!

{
	"AuthToken" : "john.smith",
	"DisasterId" : 2,
	"Latitude" : -23.1234,
	"Longitude" : 43.1234
}

Sample Response:

{
	"Success" : true
}

Possible Errors:

• Already Checked into a Disaster
• No Commitment for the given disaster, for the given user

---

CheckOut

Should already know the disaster the user is checked in, so the only parameter required is the auth token. This should check out the user from the disaster they are currently checked into.

Url: /api/checkout

Parameters:

• string AuthToken - For now this is the user's username

Sample Request:

{
	"AuthToken" : "john.smith",
}

Sample Response:

{
	"Success" : true
}

Possible Errors:

• Not Checked into a Disaster currently

Updates

• AuthToken is now essentially just Username
• Added Username field to register call
• Added AuthToken (Username) result to register call

@Redth, this looks great.

After we get an initial version working, I'd like to add 302-Not Modified to the list of possible return statuses. I'm not certain, but I think that could have a noticeable effect on battery life in a disaster zone, where communication could be somewhat spotty.

Yep it looks good to me. The only thing I can think of that we may want to have eventually are methods for changing contact info and changing password, but the important stuff is here.