Skip to content

RESTful API endpoint

Jump to bottom Edit New page
YMHuang edited this page Sep 17, 2015 · 37 revisions

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"
        }
    ]
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally