Based on the large part of requests to the Coursmos API, it is required to pass an authentication token in the HTTP header. Authentication token can be acquired using Open Authorization Protocol OAuth 2.0.

Authentication can be accomplished in two ways:

1. Web authentication.

2. Authentication with user’s login and password transfer.

Web Authentication

User will be redirected to the authentication page coursmos.com.

After authentication, user will be asked if he is ready to provide access to his account for the application.

After response, user will be redirected to the page, which URI was passed by the application in the

RedirectURI parameter.

The OAuth 2.0 protocol is well documented and has many ready-to-use samples that will help you to

integrate authorization in your application.

For authorization you will need following details:

• Authorization URL: https://api.coursmos.com/v2.0/oauth2
• Access Token URL: https://api.coursmos.com/v2.0/oauth2/token
• client_id
• client_secret

To get the client_id and client_secret, you will need to contact customer support Coursmos.com.
In request handling, you will need to fill the RedirectURI parameter.
Authentication requests with the RedirectURI parameter missing will be refused.

Authentication with user’s login and password transfer:

This authentication method allows you to get the token by simple POST request https://api.coursmos.com/v2.0/oauth2/token by passing client_id, client_secret, username, and password in the query.

This method of getting a token has some cons:

• Registered users via social networks don’t have a password in coursmos.com, that’s why
  authorization this way is impossible for them.

• User’s password is open to the application, which means that it’s not always safe.

Token passing upon request

To authorize the request, you should pass the token in the HTTP header each time:

Authorization: Bearer urWpo5CGDIBJ/39+rY9D3M1GN4VaUxHB20k9aQjPTk0=

Token lifetime

Token lifetime is 1 hour.
Then you can get it again without re-entering user’s password.
To do this, you need to use a refreshToken, which you were supposed to get with the accessToken through the authentication request.
We follow the RESTful architecture.
Here’s a small sample of our RESTful:

GET /comments – Get the comments list
GET /comments/{commentsId} – Get comments by ID
POST /comments/{commentsId} – Create comment
PUT /comments/{commentsId} – Update comment
DELETE /comments/{commentsId} – Delete comment

What if the application could not work as a RESTful ?

In our practice it can happen that some applications may not work as RESTful.
It depends on the programming language opportunities and libraries used.
Some Web browsers also may work incorrectly with RESTful, especially by cross domain requests.

For such applications, we support Method-Override.
In this case, you need to send GET requests as usual. POST, PUT, DELETE requests must be sent as a POST requests and the method name should be specified
through a URI parameter “method” or the HTTP header “X-HTTP-Method-Override”.
Example as, POST /comments/9567cdae-18c3-11e5-8a68-db6eff18924b?method=DELETE.

By Method-Override HTTP query status will be always 200 OK, and the real status of the query can be seen in the body of the response status.
Each request operation returns its status. We use standard HTTP status codes. Their description is below.
If errors occur when you run the query, more detailed information about it can be seen in the response body (the error field).
Each error is described as {“code”: , “message”: “description of the error”}
However as in samples error.code and HTTP status are often the same, they are still different values.
There are much more error codes than given in standard HTTP status.
For example, it may return {“status”: 400, “error”: {“code”: 2001, “message”: “More than one file sent.”}}

Sample of successful response query:

Content-Type: application/json

{
	"version": "2.0",
	"status": 200,
	"result": <null or result object or array of objects>		
}

Sample of response with error:

Content-Type: application/json

{
	"version": "2.0",
	"status": 405,
	"error": {
		"code": 405,
		"message": "Method Not Allowed"
	},
	"result": null
}

Error in case the token is missing or invalid:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

Unauthorized

Error in case of wrong parameters:

Content-Type: application/json
{
	"version": "2.0",
	"status": 422,
	"error": {
	"code": 422,
	"message": "Validation failed.",
	"validationDetails": {
		"newPassword": [
			"The newPassword field is required."
		]
		}
	},
	"result": null
}

During request, you may specify to the server which data exactly should be included in the response.
It optionally allows to show more data in the response and to avoid additional requests to the server.

Sample of response for GET /v2.0/comments?fields=comment,author :

{
	"version": "2.0",
	"status": 200,
	"result": [
	{
		"comment": {
			"location": "/v2.0/comments/5582a85f637c51100066bdef",
			"commentId": "5582a85f637c51100066bdef",
			"courseId": 15415671,
			"text": "I wanna learn about International Business ",
			"authorId": "8b9c37a5-ff72-77b5-d5ce-466e6d4b4a0e"
		},
		"author": {
			"fullName": "fransy bismatama",
			"alias": "fransy-bismatama",
			"userId": "8b9c37a5-ff72-77b5-d5ce-466e6d4b4a0e",
			"avatar": {
				"small": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg",
				"middle": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg",
				"large": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg"
			}
		}
		},
		{
			"comment": {
				"location": "/v2.0/comments/55824672637c51100066bb52",
				"commentId": "55824672637c51100066bb52",
				"courseId": 14904132,
				"text": "Hai",
				"authorId": "8b9c37a5-ff72-77b5-d5ce-466e6d4b4a0e"
				},
		"author": {
			"fullName": "fransy bismatama",
			"alias": "fransy-bismatama",
			"userId": "8b9c37a5-ff72-77b5-d5ce-466e6d4b4a0e",
			"avatar": {
				"small": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg",
				"middle": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg",
				"large": "//lh6.googleusercontent.com/-vRvix79DXY4/AAAAAAAAAAI/AAAAAAAAACY/xXTpvNitz2w/photo.jpg"
			}
		}
	}
}

There are such operations which their results cannot be returned immediately.
The simplest example is downloading a video file.
After you have downloaded it, it is not ready yet to be viewed because a long processing is required:
conversion to the desired format, creation of the preview, etc.
For such lazy loading operations, an HTTP 202 status and Location are returned.
This Location reports where to send GET request (Status request) to get the status of this lazy loading operation completion.

As soon as lazy loading operation is complete, regular Status request will return HTTP status 303 and in the Location box will be a link to the query result.

**Attention!
Your application should be ready to handle the status code 202 by any request to the API, except the GET requests.
Even if in the response always comes 200 or 201, at any time, it can return a 202 status.
**