Welcome to the JyMob API. Our goal is to create a RESTful API that you developers will love. Most of the JyMob core abstractions (e.g. JobPosts, JobApplications, ScreeningTests) are exposed through the API. The idea is that you can integrate JyMob's offerings in your website without having to make any database calls. All you need is accessing this API in a secure manner by making REST calls over HTTP(S)!
Although calling the API is easy, developers have much to learn and it may seem complicated at first. If you have ideas about how to further simplify the procedure, please let us know.
Basic idea is that you call the API as an app authorized by a JyMob user. The authorized app itself is associated with a JyMob user account. So, the first step is to let JyMob know that you want to be an app by creating your JyMob account. In OAuth lingo, such an app is called an OAuth Client and has a unique identifier (Client ID) and a secret. And since any JyMob user can wish to be an app, these credentials are already created for you once you sign up. Here are the initial steps:
|Client ID||JyMob generated, unique, read-only. DO NOT SHARE.|
|Client Secret||JyMob generated, unique, read-only. DO NOT SHARE.|
|An Optional Redirect URI||Optional. Configured and maintained by you. Required if you plan to call JyMob API from your website. Leave this blank if you want to use curl/wget as your app. We will redirect to this URI after actual user approves/denies authorization request.|
Two API acccess cases are of interest and thankfully, they are equivalent:
This is just a piece of cake with JyMob and is much more secure than HTTP Basic Auth! Access Token is already created for you when you sign up for JyMob. We use this method all the time to call the API ourselves. We get the access token and call curl like mad on our API tests. Here is the simple 1-2-3 process:
|1||Register, sign in and then go to the oauth client settings page.|
|2||On that screen you have your access token along with the handy clippy (for copy + paste).|
|3||Call API like: https://api.jymob.com/v1/job_posts.json?access_token=<access_token>|
If you think you compromised your access token, no problem. Just go to your Authorized Apps page, find your own app (tagged YOUR OWN APP! ) and just revoke its authorization. When you go back to your oauth client settings page, you'll be given a new access token. Snappy, isn't it? You never had to divulge or change your JyMob password. Also, you didn't have to put your password in a file in clear! That's the benefit of using OAuth.
This is a typical B2B API-usage scenario, but you'll need to do a little more work. You have a website or mobile app and you want to integrate with JyMob website so that user's resources are nicely compartmentalized but they amicably cooperate with each other. For instance, user's screening tests reside on JyMob and you get to display them to that user when s/he logs on to your website. This user has accounts on both your website and JyMob and s/he authorizes you, the user app_user, to access her/his account. Once you get the authorization, JyMob gives you an access token if you asked for it immediately as you learn that the user authorized you. Thus, access token is king. And your entire pursuit is to get the access token to act on another user's behalf after his/her consent.
This interaction typically happens on a web browser or mobile device and three parties are involved: Your website, JyMob website and the end user via a web browser. We assume that you have followed the process to register as a JyMob App or OAuth Client. Let's also assume that a human user Joe has user account on both your website and JyMob. Now follow these steps:
We suggest that you do this (usually) one-time activity over the web browser or mobile device because this involves the sophisticated OAuth song-and-dance and it is easier to just do it in the browser. You can do it using curl or command line, but you'll need cookie handling, which we strongly discourage.
Send this exact request and there will be no complications.
Response Status Code (you must provide the redirect_uri parameter)
Response Headers (Joe Approves App's Authorization) Yes, I Authorize
Response Headers (Joe Denies App's Authorization) No, thanks
The first step sends a redirect to the browser or mobile app and it then should redirect the end user to that redirect_uri, which belongs to your own server.
Thus, the returned Location header is of essence. Note the code sent (e.g. 9FFYjCmjwSUFIxN3fHXDIQkJ) in that header.
Using this code, you must request an access token immediately. If you fail to do so, the auth code may expire and your request to obtain access token will be invalidated.
Response Status Code: Case -- Success
Content-Type: application/json Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Response: Body (JSON) Case -- Success
Thus this time the access token is sent in the body and if you used SSL, this should be secure. Parse the JSON response and get the "access_token" from it.
There! You got the access token. Remember, with great power, comes great responsibility.
Save the access token along with user Joe's account on your website. This allows you to call the API using access token in future without Joe's repeated involvement in granting/denying the access. Note that access token is like password to some extent and you should save it securely.
TBD ... (Note that the default token validation period is 1 month, which is expressed in expires_in whose value is 2592000 seconds).
Now you can call the API like this:
Access Token is King!
This of course works till the user Joe continues to have your app authorized to access his account. It is assumed that Joe gives an implicit permission to you to access his JyMob resources as long as you have a valid access token (controlled by an "Authorization"). Thus, subsequent interactions can happen without explicit grant of authorization.
That's it. Browse the API.
We want to make every attempt to make it easier for you to develop your own interfaces easily, using our API. We know that you want to test out the integration before you put it in production. As of now, we don't have any staging environment as such, so all of JyMob's production data is available and you can call the API's on that. Don't worry, it is like creating a user or two at http://jymob.com and then trying things out. Go ahead, do that. The question about the redirect_uri can also be easily answered. Either you can use the same redirect_uri, or create two different user accounts (one for development and one for production) and use the production URI e.g. https://mywebsite.com/jymob_callback and development URI like http://localhost:4444/jymob_callback to handle the OAuth callback.