JyMob API Current Version: v1

  1. Introduction
  2. Details
    1. Anatomy of Request and Successful Response
      1. GET
      2. POST
      3. PUT
      4. DELETE
    2. Pagination
    3. What Errors Look Like
  3. Versioning

Introduction

Please see the home page for authentication and authorization information.

Details

Unless stated otherwise, all actions require access_token to be passed as a parameter. This is in addition to any other query string parameters. The API is designed to be uniform. Most of the RESTful resources provide a standard CRUD interface. The access control is identical to that enforced by the JyMob website. If you are not able to perform an operation on the website and it's possible using the API (or vice versa), then it is a bug. A typical request looks like:

https://api.jymob.com/v1/job_posts.json?access_token=<access_token>&search=Java+Software+Engineer

Documentation of CRUD operations on each resource shows the anatomy of HTTP request and response. Standard HTTP status codes are employed for the sake of computers and descriptive error/status messages are provided for the sake of humans. We at JyMob script these API calls all day, so this uniformity and developer-ease-of-use is of paramount importance to us. For demonstration purpose, we use the versatile cURL tool.

Anatomy of Request and Successful Response

Well, it's a standard HTTP request/response utilizing a RESTful way of accessing a resource on JyMob. We support both JSON and XML. Server determines the request based on the HTTP Accept: header or the name of the URL's path. Both the ways are available. In short, all of the following are equivalent and supported. All of them return the list of job posts available in requested format:
curl -H "Accept: application/json" 'https://api.jymob.com/v1/job_posts?access_token=<access-token>' (JSON)
curl 'https://api.jymob.com/v1/job_posts.json?access_token=<access-token>' (JSON)
curl -H "Accept: application/xml" 'https://api.jymob.com/v1/job_posts?access_token=<access-token>' (XML)
curl 'https://api.jymob.com/v1/job_posts.xml?access_token=<access-token>' (XML)

Successful response codes include:

Code Meaning
200 OK. Successful POST or PUT or DELETE.
201 CREATED. Successful creation of a resource.

Of course, you can use any tool or programming language to craft a JyMob API request and send it. We support the standard HTTP verbs: GET, POST, PUT, DELETE. Here is what the interaction looks like (for the Job Post resource and an example access-token):

Verb Example HTTP (cURL) Request Note: Accept Header Corresponding HTTP Response Note: Status Code
GET

You typically use GET request in listing a particular resource or listing a set of resources. The URL clearly distinguishes the target (singular or plural). In this case, we show listing of two resources on second page. Note that pagination is built in.

curl -i -v -H "Accept: application/json" 'https://api.jymob.com/job_posts?access_token=...&page=2&per_page=2'

Specifies Accept Header
GET /job_posts?access_token=...&page=2&per_page=2 HTTP/1.1
User-Agent: curl/7.21.0 (...)
Host: IP-address-of-api.jymob.com
Accept: application/json
          
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Etag: "f7a3f34bac7483e6e69539b5efeeea36"
Cache-Control: max-age=0, private, must-revalidate
...
[{"job_post":{"description":"Related to Quick Challenge: 1","external_url":null,"id":3,"location":"Someplace","organization_id":1,"summary":"Testing this out ..."}},{"job_post":{"description":"Related to Quick Challenge: 1","external_url":null,"id":4,"location":"Someplace","organization_id":1,"summary":"Testing this out ..."}}]
          
POST

curl -i -v -F "location=Mountain View, CA" -F "organization_name=Google Inc." -F "access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986" -F "summary=This is a test Job" -F "description=Drive and coordinate a team of user experience designers in the definition of new and established product categories" https://api.jymob.com/job_posts.json

No Accept Header, but URL path specifies JSON -F simulates form submission, -d works too
POST /job_posts.json HTTP/1.1
User-Agent: curl/7.21.0 (...)
Host: IP-address-of-api.jymob.com
Accept: */*
Expect: 100-continue
Content-Type: multipart/form-data; boundary=--------------------------87abbb7cf081
          
HTTP/1.1 201 Created
Location: https://api.jymob.com/job_posts/25
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
...
{"job_post":{"description":"Drive and coordinate a team of user experience designers in the definition of new and established product categories","external_url":null,"id":25,"location":"Mountain View, CA","organization_id":13,"summary":"This is a test Job"}}%
          
PUT

There are two ways to send PUT requests. One uses the direct way of specifying the verb PUT, the other way is to specify a specific header (X-HTTP-Method-Override: PUT) with a POST request. For instance, observe that the above POST request created the Job Post resource with ID 25. Now, let's change the location attribute of this resource to "New York City, NY" from the current "Mountain View, CA".

curl -i -v -X PUT -d 'access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986' -d "location=New York City, NY" http://127.0.0.1:3001/job_posts/25.json

Or, change the summary by specifying the header with a POST request as in:
curl -i -H "Accept: application/json" -H "X-HTTP-Method-Override: PUT" -X POST -d 'access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986' -d 'summary=This is NOT a test job' http://127.0.0.1:3001/job_posts/25

PUT /job_posts/25.json HTTP/1.1
User-Agent: curl/7.21.0 (...)
Host: IP-address-of-api.jymob.com
Accept: */*
Content-Length: 76
Content-Type: application/x-www-form-urlencoded
          
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
Empty Body
          
DELETE

Like PUT, there are two ways to send DELETE requests. One uses the direct way of specifying the verb DELETE, the other way is to specify a specific header (X-HTTP-Method-Override: DELETE) with a POST request. For instance, observe that the above POST request created the Job Post resource with ID 25. Now, let's try to delete it.

curl -v -i -H "Accept: application/json" -X DELETE -d 'access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986' http://127.0.0.1:3001/job_posts/25

Or, curl -v -i -H "Accept: application/json" -H "X-HTTP-Method-Override: DELETE" -X POST -d 'access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986' http://127.0.0.1:3001/job_posts/25

DELETE /job_posts/25 HTTP/1.1
User-Agent: curl/7.21.0 (...)
Host: IP-address-of-api.jymob.com
Accept: application/json
Content-Length: ...
Content-Type: application/x-www-form-urlencoded

          

In either of these, you get an access violation exception because you need to be an administrator in order to delete a job post.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
...
{"message":"You do not have sufficient privileges to perform this operation. Contact Support.","details":"..."}%
          

A Word About Pagination

Lists of resources should usually be paginated. This has implications on the server-side performance. If you asked for all the screening tests and there are 100s of them, we may end up creating huge load on the server in addition to returning resources that you may not be interested in. So, we have hooks and reasonable defaults. The two parameters that control this behavior are:

  1. per_page: Specifies the number of results per page. Default is 10, capped at 30. This is analogous to the SQL-fame LIMIT.
  2. page: Specifies the ID of the page you are interested in. Default is 1. This is analogous to the SQL-fame OFFSET.

Using these two parameters, we believe you can easily build your own pagination control.

What Errors Look Like

No surprises here as well. We piggyback on appropriate HTTP response codes and we use following codes to indicate error:

Code Meaning
400 Invalid Request. Some kind of error on client's part. This comes with copious and helpful error messages.
401 Unauthorized Access. Generally indicates invalid or expired access token or that you do not have privilege to perform an operation.
403 Forbidden. Sent when you should not be attempting the said operation.
404 Not Found. Non-existent Resource requested.
406 Unacceptable Response. You should not get this response code and if you do get it (it's software after all :-)), it is a bug. Please let us know.
422 Unprocessable Entity. Generally indicates that required information was not provided while creating a resource.
500 (The Dreaded) Internal Server Error. Some kind of error on server's part. This comes with copious and helpful error messages. This also means error on our part. Please let us know.
501 Not Implemented. Thrown when you try to invoke an action that is not implemented. This means that there is a chance that that action will be implemented in future.

When an exception is thrown, the messages are designed to be helpful so that you can correct the problems on your own in most cases. In both JSON and XML formats, you see "message" and "details" elements that are usually enough to know more about what went wrong. In a few cases, they are difficult to decipher (we apologize for those in advance) and you will need to contact us to resolve them.

If you run into issues while creating resources, the error messages are usually very descriptive. Together with the HTTP status code 422 (unprocessable entity) these error messages give you enough to determine what went wrong:

curl -i -v -F "organization_name=FooBar"  -F "access_token=4fcdab32-3777-4fc0-85fd-71f4ef5c7986" https://api.jymob.com/job_posts.json
...
HTTP/1.1 422 ⇐ (Watch the error code)
Content-Type: application/json; charset=utf-8
...

{"location":["can't be blank"],"summary":["Without external URL, a summary for the job is required"],"description":["Without external URL, a description for the job is required","Please provide a better job description (use more appropriate keywords, for instance), we could not generate a job profile."]}

Occasionally, you may run into issues when certain required parameters are not specified by the API client. In such cases, a message of the form Parameters: [<parameter1>, <parameter2>...] are required for this action is returned in the response. The status code returned is one of 4xx.

You may also get errors when you specify parameters that are prohibited for a particular operation. The error message returned in the response in such cases is of the form: Parameters: [<parameter1>, <parameter2>...] are prohibited for this action

Sometimes, you may get a Timeout Error which comes with an HTTP status code of 500. This means that the response did not return in that period. Our QOS is that the timeout is set at 10 seconds (to fetch the data). Contact us if you get this error.

Versioning

For an API, versioning is one of the most important considerations. We believe we have an interesting take on versioning. We strive hard to be backward compatible (however, to be honest, we may end up being incompatible in (hopefully) few cases).

  • At any point in time, there is a default version of the API implementation. This default version is reachable by just sending request to the canonical API URL: https://api.jymob.com
  • Every api version is available at the URI: /v<id>, for example, /v1.
  • If v1 is the default version, then a resource in question is available at both https://api.jymob.com/resource-url-with-params and https://api.jymob.com/v1/resource-url-with-params ⇐ Preferred.
  • Since the default version is a moving target, it is always safe to commit to explicit versions in URIs. If you do not use the version identifier in the URL, a friendly X-API-Version-Warning header is added to the response.

Version deprecation is something we are sensitive to. We'll update this section as we make progress. For now, all the versions will be available all the time.