Skip to content

RESTful API endpoint

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

DEPRECATED

The latest RESTful API documentation, please go to https://openisdm.github.io/VMS-API-doc

Table of Contents generated with DocToc

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" : {
    	"id": 1,
    	"name_zh_tw": "臺北市",
    	"name_en": "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

If the attribute is missing, it will return the following response:

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"
        }
    ]
}

If the username or email address was used, it will return the following response:

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

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

If the password strength is not enough, it will return the following response:

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Register",
            "field": ["passsword"],
            "code": "not_enough_password_strength"
        }
    ]
}

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 & retrieve volunteer's own account

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" : {
    	"id": 1,
    	"name_zh_tw": "臺北市",
    	"name_en": "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": {
        "href": "https://vms.app/api/v1.0/users/me/exeperience" 
    },
    "education": [
        "href": "https://vms.app/api/v1.0/users/me/education"
    ],
    "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"
    },
    "avatar_url": "https://vms.app/upload/image/avatar/jimlin_366b4c757bff8643b9f97441a974d94d42f5877b.jpeg"
},
    "updated_at": "2015-09-22 11:38:04",
    "created_at": "2015-09-20 22:30:47"
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"
        }
    ]
}

9. Update volunteer's own profile

Endpoint Action Description
/users/me PUT Update volunteer's own profile
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
PUT Data

The data is optional.

{
   "phone_number": "0988123456",
   "emergency_contact": "Johnson Su",
   "emergency_phone": "0978123456"
}

Note: If volunteer wants to change his/her password, please invoke /users/me/password API endpoint.

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" : {
    	"id": 1,
    	"name_zh_tw": "臺北市",
    	"name_en": "Taipei City"
    },
    "address": "128 Academia Road, Section 2, Nankang Dist.",
    "phone_number" : "0988123456",
    "email": "[email protected]",
    "emergency_contact": "Johnson Su",
    "emergency_phone": "0978123456",
    "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": {
        "href": "https://vms.app/api/v1.0/users/me/exeperience" 
    },
    "education": [
        "href": "https://vms.app/api/v1.0/users/me/education"
    ],
    "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"
    },
    "avatar_url": "https://vms.app/upload/image/avatar/jimlin_366b4c757bff8643b9f97441a974d94d42f5877b.jpeg"
},
    "updated_at": "2015-09-22 11:38:04",
    "created_at": "2015-09-20 22:30:47"
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"
        }
    ]
}

10. Volunteer changes his/her own password

Endpoint Action Description
/users/me/password PUT Volunteer changes his/her own profile
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
PUT Data
{
   "existing_passowrd": "MYPASSW0RD",
   "new_password": "MY_NEW_PASSWoRD"
}
Response
Success
HTTP/1.1 204 No Content
Failure

If the volunteer doesn't have right to access (ex. existing_password is not correct), 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"
        }
    ]
}

11. Upload a new avatar image

Endpoint Action Description
/users/me/avatar POST Upload volunteer's own avatar image
Request format
Header
  • Content-Type: image/[jpeg | png]
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data

This endpoint may support base64 encoded image data.

{
   "avatar": "/Users/jimlin/images/my_avatar.jpeg",
   "skip_profile": false
}

The skip_profile is optional. if the value is true, it will skip to return volunteer's profile object.

Response
Success

The skip_profile value is false. It will return the following response:

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" : {
    	"id": 1,
    	"name_zh_tw": "臺北市",
    	"name_en": "Taipei City"
    },
    "address": "128 Academia Road, Section 2, Nankang Dist.",
    "phone_number" : "0988123456",
    "email": "[email protected]",
    "emergency_contact": "Johnson Su",
    "emergency_phone": "0978123456",
    "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": {
        "href": "https://vms.app/api/v1.0/users/me/exeperience" 
    },
    "education": [
        "href": "https://vms.app/api/v1.0/users/me/education"
    ],
    "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"
    },
    "avatar_url": "https://vms.app/upload/image/avatar/jimlin_366b4c757bff8643b9f97441a974d94d42f5877b.jpeg"
},
    "updated_at": "2015-09-22 11:38:04",
    "created_at": "2015-09-20 22:30:47"

The skip_profile value is true or not be set (default value is true). It will return the following response:

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

{
    "avatar_url": "https://vms.app/upload/image/avatar/jimlin_366b4c757bff8643b9f97441a974d94d42f5877b.jpeg"
},
    "updated_at": "2015-09-22 11:38:04",
    "created_at": "2015-09-20 22:30:47"
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 image is uncorrect, it will return the following response:

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

{
    "message": "Something wrong",
    "errors": [
        {
            "code": "unable_to_upload_avatar"
        }
    ]
}

12. Get country cities

Endpoint Action Description
/country/[COUNTRY_NAME]/[STATE_NAME]/cities GET Get cities list in the country
/country/[COUNTRY_NAME]/[STATE_NAME]/cities?locale=zh-TW GET Get cities list in the country in Traditional Chinese

NOTICE: This endpoint and result format MAY be changed!

Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
Response
Success

For example:

GET /country/Taiwan/Taiwan/cities?locale=zh-TW

It will return the following response:

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

{
    "country_zh_tw": "臺灣",
    "cities": [
        {
            "id": 1,
            "name": "臺北市"
        },
        {
            "id": 2,
            "name": "新北市"
        },
        {
            "id": 3,
            "name": "桃園市"
        },
        {
            "id": 4,
            "name": "臺中市"
        },
        {
            "id": 5,
            "name": "臺南市"
        },
        {
            "id": 6,
            "name": "新竹市"
        },
        {
            "id": 7,
            "name": "嘉義市"
        },
        {
            "id": 8,
            "name": "新竹縣"
        }, 
        {
            "id": 9,
            "name": "苗栗縣"
        },
        {
            "id": 10,
            "name": "新北市"
        },
        {
            "id": 11,
            "name": "彰化縣"
        },
        {
            "id": 12,
            "name": "南投縣"
        },
        {
            "id": 13,
            "name": "雲林縣"
        },
        {
            "id": 14,
            "name": "嘉義縣"
        },
        {
            "id": 15,
            "name": "屏東縣"
        },
        {
            "id": 16,
            "name": "花蓮縣"
        },
                {
            "id": 17,
            "name": "臺東縣"
        },
        {
            "id": 18,
            "name": "澎湖縣"
        },
        {
            "id": 19,
            "name": "金門縣"
        },
        {
            "id": 20,
            "name": "連江縣"
        }
   ]
}
Failure

If the country or state name don't exist, it will return the following response:

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

{
    "message": "Unable to find cities",
    "errors": [
        {
            "code": "unable_to_find_cities"
        }
    ]
}

13. Add a new experience

Endpoint Action Description
/users/me/experience POST Volunteer adds a new expereience
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    "name": "Academia Sinica",
    "job_title": "Research Assistant",
    "start_year": 2014,
    "end_year": null
}
Response
Success

It will return the following response, it includes the experience id:

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
    "experience_id": "jimlin_1"
}
Failure

If the attribute is missing, it will return the following response:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Experience",
            "field": ["job_title"],
            "code": "missing_field"
        }
    ]
}

14. Update an experience

Endpoint Action Description
/users/me/experience/[EXPERIENCE_ID] PUT Volunteer updates his/her own existing expereience
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    "name": "Academia Sinica",
    "job_title": "Research Assistant",
    "start_year": 2014,
    "end_year": null
}
Response
Success
HTTP/1.1 204 No Content
Failure

If the attribute is missing, it will return the following response:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Experience",
            "field": ["job_title"],
            "code": "missing_field"
        }
    ]
}

If the experience id doesn't exist, it will return the following response:

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

{
    "message": "Unable to find experience",
    "errors": [
        {
            "code": "unable_to_find_experience"
        }
    ]
}

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

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

{
    "message": "Not have right to access",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}

15. Delete an experience

Endpoint Action Description
/users/me/experience/[EXPERIENCE_ID] DELETE Volunteer deletes his/her own existing expereience
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 attribute is missing, it will return the following response:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Experience",
            "field": ["job_title"],
            "code": "missing_field"
        }
    ]
}

If the experience id doesn't exist, it will return the following response:

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

{
    "message": "Unable to find the experience",
    "errors": [
        {
            "code": "unable_to_find_experience"
        }
    ]
}

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

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

{
    "message": "Not have right to access",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}

16. Add a new education

Endpoint Action Description
/users/me/education POST Volunteer adds a new education
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    "school": "NCKU",
    "degree": 5,
    "field_of_study": "Computer Science",
    "start_year": 2012,
    "end_year": 2014
}
Response
Success

It will return the following response, it includes the experience id:

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
    "education_id": "jimlin_1"
}
Failure

If the attribute is missing, it will return the following response:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Education",
            "field": ["degree"],
            "code": "missing_field"
        }
    ]
}

17. Update an education

Endpoint Action Description
/users/me/education/[EDUCATION_ID] PUT Volunteer updates his/her own existing education record
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    "school": "National Cheng Kung University",
    "degree": 5,
    "field_of_study": "Computer Science",
    "start_year": 2012,
    "end_year": 2014
}
Response
Success
HTTP/1.1 204 No Content
Failure

If the attribute is missing, it will return the following response:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Education",
            "field": ["degree"],
            "code": "missing_field"
        }
    ]
}

If the experience id doesn't exist, it will return the following response:

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

{
    "message": "Unable to find education",
    "errors": [
        {
            "code": "unable_to_find_education"
        }
    ]
}

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

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

{
    "message": "Not have right to access",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}

18. Delete an education

Endpoint Action Description
/users/me/experience/[EDUCATION_ID] DELETE Volunteer deletes his/her own existing education
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

{
    "result": [
        {
            "name": "Disaster Survellience",
            "head_line": ""<strong>Dis</strong>aster Survellience""
        },
        {
            "name": "Disaster Recovery",
            "head_line": ""<strong>Dis</strong>aster Recovery""
        },
    ]
}
Failure

If the experience id doesn't exist, it will return the following response:

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

{
    "message": "Unable to find education",
    "errors": [
        {
            "code": "unable_to_find_education"
        }
    ]
}

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

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

{
    "message": "Not have right to access",
    "errors": [
        {
            "code": "cannot_access"
        }
    ]
}

19. Get skill keyword

Endpoint Action Description
/skill_candidates/[KEYWORD] GET Get skill keyword
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
Response
Success
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "result": [
        {
            "name": "Disaster Survellience",
            "id": 34,
            "head_line": "<strong>Dis</strong>aster Survellience"
        },
        {
            "name": "Disaster Recovery",
            "id": 35,
            "head_line": "<strong>Dis</strong>aster Recovery"
        },
    ]
}

If the keyword is not found, it will return the following response:

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

{
    "result": [
    ]
}

The result value is an empty array.

Failure

To be continuce.

20. Get equipment keyword

Endpoint Action Description
/equipment_candidates/[KEYWORD] GET Get equipment keyword
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
Response
Success
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "result": [
        {
            "name": "Car",
            "id": 21,
            "head_line": "<strong>Ca</strong>r"
        },
        {
            "name": "Camera",
            "id": 43,
            "head_line": "<strong>Ca</strong>mera"
        },
    ]
}

If the keyword is not found, it will return the following response:

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

{
    "result": [
    ]
}

The result value is an empty array.

Failure

To be continuce.

21. Update volunteer's skill (NOT CONFIRMED!)

Endpoint Action Description
/users/me/skills POST Update volunteer's skill
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    skills: [
        "Swimming",
        "Programming",
        "Rope rescue"
    ],
    existing_skill_index: [
        0,
        1
    ]
}

The Swimming and Programming skills exist and Rop rescue skill doesn't exist. The existing_skill_index means the skills array index of existing skills.

Response
Success
HTTP/1.1 204 No Content
Failure

If there is a missing field, it will return the following request:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Skills",
            "field": ["existing_skill_index"],
            "code": "missing_field"
        }
    ]
}

If something wrong happens, it will return the following request:

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

{
    "message": "Unable to execute",
    "errors": [
        {
           "code": "the_exceed_index_value"
        }
    ]
}

22. Update volunteer's equipment (NOT CONFIRMED!)

Endpoint Action Description
/users/me/equipment POST Delete volunteer's equipment
Request format
Header
  • Content-Type: application/json
  • X-VMS-API-Key: d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
  • X-VMS-AUTH-ACCESS-TOKEN: jimlin:d6527aa8bcf55187490154283e4d2a1a268a94ead2322f883276a7c3cb52cd09
POST Data
{
    "equipment": [
        "Car",
        "Scooter",
        "Camera"
    ],
    "existing_equipment_index": [
        0,
        1,
        2
    ]
}

The Car, Scooter and Camera equipment exist. The existing_equipment_index means the equipment array index of existing equipment.

Response
Success
HTTP/1.1 204 No Content
Failure

If there is a missing field, it will return the following request:

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

{
    "message": "Validation failed",
    "errors": [
        {
            "resource": "Skills",
            "field": ["existing_equipment_index"],
            "code": "missing_field"
        }
    ]
}

If something wrong happens, it will return the following request:

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

{
    "message": "Unable to execute",
    "errors": [
        {
           "code": "the_exceed_index_value"
        }
    ]
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally