ibrahimoluwadamilare / sinch-laravelbackend

Creating a Dating Application with Sinch: RESTful API

Tuts+ Tutorial: Creating a Dating Application with Sinch: RESTful API

Instructor: Carlos Cessa

In this tutorial, we're going to create a dating application for iOS similar to Tinder. For voice and messaging, we will leverage the Sinch platform, making use of its powerful SDK. In the first part, we will focus on the development of a RESTful API to store and retrieve user information. In the second part, the iOS client will hook into this API to find nearby users based on its current location.

Source Files for the Tuts+ Tutorial: Creating a Dating Application with Sinch: RESTful API

Read this tutorial on Tuts+

API Documentation

Sessions Resource

The url for the REST API sessions resource, it's located in the following URL:

• http://YOUR_API_URL/sessions

It has support for the following methods:

• POST - Create an user session
• DELETE/{token} - Destroy an existing user session

---

POST sessions

Start an user session in the system.

• Endpoint URL - http://YOUR_API_URL/sessions
• Request Method - POST
• Response Format - JSON
• Requires Authentication - No
• Response Codes - 200 | 403

Parameters

{
	"email"		: "[email protected]",
	"fbId"		: "USER_FB_ID",
	"gender"	: "male",
	"location"	: { "lat" : 37.427208696456866, "lon" : -122.17097282409668 }
	"mobile"	: "141649811",
	"name"		: "John Doe"
}

Altough the only required parameters are: fbId and either email or mobile. It's suggested to send all the information, to start a new session the system uses only the email and fbId or the mobile and fbId. However if the user attempting to start a session does not exists, the system will attempt to create a new user record, in order for this to work all the information previously mentioned must be sent.

Responses

Successful request

{
	"user_id"	: "551335b76803fa1e068b4585",
	"user_name"	: "John Doe",
	"token"		: "55136a586803fa1f068b4581"
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "ERROR_INVALID_PARAMETERS",
	"status"	: 403
}

---

DELETE sessions/{token}

Removes an existing user session from the system.

• Endpoint URL - http://YOUR_API_URL/sessions/{token}
• Request Method - DELETE
• Response Format - JSON
• Requires Authentication - Yes
• Response Codes - 200 | 403

Parameters

{
	
}

Responses

Successful request

{}

Unsuccessful request

{
	"error"		: "ERROR_REMOVING_SESSION",
	"status"	: 403
}

---

Users Resource

The url for the REST API users resource, it's located in the following URL:

• http://YOUR_API_URL/users

It has support for the following methods:

• GET - Retrieve a list of users
• GET/{id} - Retrieve a single user record
• POST - Create an user in the database
• PUT/{id} - Update an existing user information
• DELETE/{id} - Remove an user record

---

DELETE users/{id}

Removes an existing user record.

• Endpoint URL - http://YOUR_API_URL/users/{id}
• Request Method - DELETE
• Response Format - JSON
• Requires Authentication - Yes
• Response Codes - 200 | 403

Parameters

{
	"token"		: "55136a586803fa1f068b4581"
}

Responses

Successful request

{
	"_id"		: "551335b76803fa1e068b4585",
	"email"		: "[email protected]",
	"fbId"		: "USER_FB_ID",
	"gender"	: "male",
	"location"	: {
		type		: "Point",
		coordinates	: [ -122.17097282409668, 37.427208696456866 ]
	},
	"mobile"	: "141649811",
	"name"		: "John Doe"
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "PERMISSION_DENIED",
	"status"	: 403
}

---

GET users

Retrieve a list of existing users in the system.

• Endpoint URL - http://YOUR_API_URL/users
• Request Method - GET
• Response Format - JSON
• Requires Authentication - No
• Response Codes - 200 | 403

Parameters

{
	"distance"	: 150000,
	"token"		: "55136a586803fa1f068b4581"
}

The parameters in the request are optional, for a unregistered user the method will return a list of all the available users in the system.

If a token and distance parameter are given, the system will return the users that are located near the user with the active session at a maximum distance as specified in the request distance parameter, given in meters. The obtained result in a query for a logged in user will exclude the user issuing it.

Responses

Successful request

{
	[
		{
			"_id"		: "551335b76803fa1e068b4585",
			"email"		: "[email protected]",
			"fbId"		: "USER_FB_ID",
			"gender"	: "male",
			"location"	: {
				type		: "Point",
				coordinates	: [ -122.17097282409668, 37.427208696456866 ]
			},
			"mobile"	: "141649811",
			"name"		: "John Doe"
		}
	]
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "PERMISSION_DENIED",
	"status"	: 403
}

---

GET users/{id}

Retrieve an existing user record from the system.

• Endpoint URL - http://YOUR_API_URL/users/{id}
• Request Method - GET
• Response Format - JSON
• Requires Authentication - Yes
• Response Codes - 200 | 403

Parameters

{
	"token"		: "55136a586803fa1f068b4581"
}

The id of the user to retrieve does not need to match the id of the user with the active session, any user can retrieve the details for all the users.

Responses

Successful request

{
	"_id"		: "551335b76803fa1e068b4585",
	"email"		: "[email protected]",
	"fbId"		: "USER_FB_ID",
	"gender"	: "male",
	"location"	: {
		type		: "Point",
		coordinates	: [ -122.17097282409668, 37.427208696456866 ]
	},
	"mobile"	: "141649811",
	"name"		: "John Doe"
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "PERMISSION_DENIED",
	"status"	: 403
}

---

POST users

Create an user record in the system.

• Endpoint URL - http://YOUR_API_URL/users
• Request Method - POST
• Response Format - JSON
• Requires Authentication - No
• Response Codes - 200 | 403

Parameters

{
	"email"		: "[email protected]",
	"fbId"		: "USER_FB_ID",
	"gender"	: "male",
	"location"	: { "lat" : 37.427208696456866, "lon" : -122.17097282409668 }
	"mobile"	: "141649811",
	"name"		: "John Doe"
}

The only optional parameters are the email and mobile, however one of those must be present and is used to start an user session in the system.

Responses

Successful request

{
	"_id"		: "551335b76803fa1e068b4585",
	"email"		: "[email protected]",
	"fbId"		: "USER_FB_ID",
	"gender"	: "male",
	"location"	: {
		type		: "Point",
		coordinates	: [ -122.17097282409668, 37.427208696456866 ]
	},
	"mobile"	: "141649811",
	"name"		: "John Doe"
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "ERROR_INVALID_PARAMETERS",
	"status"	: 403
}

---

PUT users/{id}

Update an existing user record.

• Endpoint URL - http://YOUR_API_URL/users/{id}
• Request Method - PUT
• Response Format - JSON
• Requires Authentication - Yes
• Response Codes - 200 | 403

Parameters

{
	"gender"	: "female",
	"name"		: "Jane Doe",
	"token"		: "55136a586803fa1f068b4581"
}

Responses

Successful request

{
	"gender"	: "female",
	"name"		: "Jane Doe"
}

Unsuccessful request

In the case of an unsuccessful request the API will send a 403 error code.

{
	"error"		: "PERMISSION_DENIED",
	"status"	: 403
}