RESTful API endpoint

Introduction

This is a DRAFT.

The POST and PUT requests body must be JSON format and the Content-Type header also set to application/json. In addition, for authenticating request, the X-VMS-API-Key set to your application key.

API versioning

• Prefix URI: /api/v1.0/

Endpoint on v1.0

Volunteers account

1. Register a new account

Endpoint	Action	Description
/register	POST	Create a new volunteer account

Request format

Header

• Content-Type: application/json
• X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09

POST Data

{
    "username" : "jimlin",
    "password" : "MYPASSW0RD",
    "first_name" : "Lin",
    "last_name" : "Jim",
    "birth_year" : 2015,
    "gender" : "male",
    "city" : "Taipei City",
    "address" : "128 Academia Road, Section 2, Nankang Dist.",
    "phone_number" : "0912345678",
    "email" : "[email protected]",
    "emergency_contact" : "Jeremy Lin",
    "emergency_phone" : "0919119119"
}

Response example

Success

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://vms.app/api/v1.0/users/me

{
    "href": "https://vms.app/api/v1.0/users/me",
    "username": "jimlin",
    "auth_access_token": "56f4da226eb22caa0633023bfdd402658e5c6501c972e83bfb2866f2112b103f"
}

Failure example

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Register",
            "field": ["username", "password"],
            "code": "missing_field"
        }
    ]
}

2. Login

Endpoint	Action	Description
/auth	POST	Volunteer logs in the system

Request format

Header

• Content-Type: application/json
• X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09

POST Data

{
    "username": "jimlin",
    "password": "MYPASSW0RD"
}

Response

Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Location: https://vms.app/api/v1.0/users/me

{
    "href": "https://vms.app/api/v1.0/users/me"
    "auth_access_token": "56f4da226eb22caa0633023bfdd402658e5c6501c972e83bfb2866f2112b103f"
}

Failure

If the volunteer's credential is wrong, it will return the following response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
    "message": "Authentication failed",
    "errors": [
        {
            "code": "incorrect_login_credentials"
        }
    ]
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Register",
            "field": ["username", "password"],
            "code": "missing_field"
        }
    ]
}

3. Logout

Endpoint	Action	Description
/auth	DELETE	Volunteer logs out the system

Request format

Header

• Content-Type: application/json
• X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
• X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09

Response

Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "message": "Successfully logged out"
}

Failure

If the volunteer's auth_access_token doesn't exist, it will return the following response:

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
    "message": "Failed to logout",
    "errors": [
        {
            "code": "no_existing_auth_access_token"
        }
    ]
}

4. Authentication

Endpoint	Action	Description
/users/me	GET	Authenticate volunteer and get volunteer information

Request format

Header

• Content-Type: application/json
• X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
• X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09

Response

Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "username": "jimlin",
    "first_name": "Lin",
    "last_name": "Jim",
    "birth_year": 2015,
    "gender": "male",
    "city": "Taipei City",
    "address": "128 Academia Road, Section 2, Nankang Dist.",
    "phone_number" : "0912345678",
    "email": "[email protected]",
    "emergency_contact": "Jeremy Lin",
    "emergency_phone": "0919119119",
    "introduction": "I’m a genius. I Work on Data science/analytics and have excellent skills with Matlab and Ruby programming. My hobbies is sporting.",
    "experience":[
        {
            "company": "Academia Sinica",
            "job_title": "Research assistant",
            "start_year": 2014,
            "end_year": null,
        }
    ],
    "education": [
        {
            "school": "NCKU",
            "degree": "master",
            "start_year": 2012,
            "end_year": 2014  
        }
    ]
}

Failure

If the volunteer doesn't have right to access, it will return the following response:

HTTP/1.1 404 Forbidden
Content-Type: application/json;charset=UTF-8

{
    "message": "Forbidden to access",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}

5. Verify email address

Endpoint	Action	Description
/email_verification/[EMAIL_ADDRESS]	POST	Resend a verification email
/email_verification/[EMAIL_ADDRESS]/[VERIFICATION_TOKEN]	GET	Verify volunteer's email

Results

To be continued.

HTTP Error