RESTful API endpoint

Table of Contents generated with DocToc

• Introduction
• API versioning
• Endpoint on v1.0
  • HTTP Response Description
  • Volunteers account
    • 1. Register a new account
    • 2. Login
    • 3. Logout
    • 4. Authentication
    • 5. Resend email address verification
    • 6. Verify email address
    • 7. Request for a password reset
    • 8. Reset passowrd

Introduction

This is a DRAFT.

If you have any problems, please create an issue on GitHub.

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

HTTP Response Description

The HTTP status code 2XX represents the request was executed successfully. Otherwise, the HTTP status code 4XX represents the request unable to execute.

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": "Login",
            "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 204 No Content

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  
        }
    ],
    "projects": {
        "href": "https://vms.app/api/v1.0/users/me/projects"
    },
    "processes": {
        "participating_number": 3,
        "participated_number": 8,
        "href": "https://vms.app/api/v1.0/users/me/proccesses"
    }
}

Failure

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

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

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

5. Resend email address verification

Endpoint	Action	Description
/email_verification/[EMAIL_ADDRESS]	POST	Resend a verification email. A new verification email will send to volunteer's mailbox.

Request format

Header

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

POST Data

None

Response

Success

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

{
    "message": "Resend verification email successfully"
}

Failure

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

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

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

6. Verify email address

Endpoint	Action	Description
/email_verification/[EMAIL_ADDRESS]/[VERIFICATION_TOKEN]	PUT	Verify volunteer's email. The volunteer must be authenticated successfully.

• EMAIL_ADDRESS: Volunteer's email address
• VERIFICATION_TOKEN: A unique token for identifying

Request format

Header

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

PUT Data

None

Response

Success

HTTP/1.1 200 Ok

{
    "message": "Successful email verification"
}

Failure

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

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

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

If the verification token is unvalidated or expired, it will return the following response:

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

{
    "message": "Unvalidated or expired verification token",
    "errors" [
        {
           "code": "unvalidated_expired_verification_token"
        }
    ]
}

7. Request for a password reset

Endpoint	Action	Description
/request_password_reset	POST	Volunteer forgot his/her password. It sends a password reset email to the volunteer

Request format

Header

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

POST Data

The /request_password_reset API accepts two kinds of fields

email:

{
   "email": "[email protected]"
}

username:

{
   "username": "[email protected]"
}

Response

Success

HTTP/1.1 204 No Content

Failure

If the field is misssing, it will return the following response:

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

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

If the email is unvalidated, it will return the following response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Request password reset",
            "field": ["username"],
            "code": "unvalidated_username"
        }
    ]
}

8. Reset passowrd

Endpoint	Action	Description
/reset_password/[EMAIL_ADDRESS]/[REST_PASSWORK_TOKEN]	POST	Use reset password token to valdiate the reuqest

Request format

Header

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

POST Data

{
   "password": "password"
}

Response

Success

HTTP/1.1 204 No Content

Failure

If the field is misssing, it will return the following response:

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

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

If the volunteer's password is unsecure, it will return the following response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Password reset",
            "field": ["password"],
            "code": "unsecure_password"
        }
    ]
}

If the volunteer's email or reset passowrd are unvalidated, it will return the following response:

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

{
    "message": "Not validated token",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}