I guess some of you know that hh.ru has an open API (we told about it here and here ), which is used not only by us, but also by third-party developers. With it, for example, you can analyze the market in great detail on large volumes of relevant data.

I conceived a series of two articles: in this I will show how you can quickly and simply start using the API, and in the next I will do a small project recommending current vacancies on your resume.

First, briefly about what our API generally is, where and how it is used.

API features

To quickly get an idea of ​​the capabilities of the API, pay attention, for example, to our mobile applications for the applicant ( Android , iOS ) and the employer ( Android , iOS ). They work through the API.
')
For example, external developers can get all current and archived jobs with salaries and other details. And this is almost 400 thousand live vacancies and even the devil knows how many archival ones. Those who want to analyze the market, play around with a lot of real data - you are here.

Through the API, job search works. Various reference books are available: regions used on the site, specialization of employees, industry companies, metro stations and so on. Authorized users can work with your vacancies or resumes: depending on whether you are an employer or a job seeker. For employers there is a job search and the opportunity to work with them.

For more information, refer to our documentation .

How does the API work?

All interaction occurs about the HTTPS protocol in the best traditions of REST. We get something - do a GET request, delete - DELETE, create - POST, edit - PUT. Data exchange is performed in JSON format. Some operations are available without authorization, others are not. An authorized user can act as an employer or applicant. It depends on what methods are available to him. For authorization, OAuth2 protocol is used (I will explain on how to do this on the fingers below). You can work with data from any of our sites . Details in the “ General Information ” section of the documentation.

Beginning of work

In order to start working with data available without authorization, you will not need anything. We look in the documentation , what methods can be used; For example, if you want to see jobs

curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies' 

Please note that you need to pass the User-Agent header. Without it will not work.

For job search, you can set different parameters .
For example, you can search for a job by the Java keyword in Moscow at the Alekseevskaya metro station

 curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies?text=java&area=1&metro=6.8' 

The area and metro values ​​can be obtained from reference books.

Authorization

As already mentioned, OAuth2 is used for authorization.
To do something from under the user, it is required to get a token and transfer this token in the header when prompted. To get a token for your user, it is enough to generate it in the API interface. Go to your account on https://dev.hh.ru and click on the button “Generate token”.

In order for other users to perform actions in your application, you must first create this application in your account. Add the application by specifying the redirect URI. The user will automatically return to this address after authorization.

After adding the application, it will be assigned a Client ID and Client Secret.

How does authorization work?

In your application, you place a link to the authorization, indicating in it the Client ID of the application, for example,

 https://hh.ru/oauth/authorize?response_type=code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA 

When a user follows this link, a special code is generated for him on our side. And our website redirects the user back to your application (by the redirect URI that was specified when registering the application), adding a parameter containing the code to the address of your application. For example:

 http://yourapphost/?code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8 

After that, you pull out the code from this address and use it to get the token by making a POST request to the API, passing the code, client_id and client_secret.

 curl -k -X POST -H 'User-Agent: api-test-agent' -d 'grant_type=authorization_code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA&client_secret=JS33UVG3J6JANNEATPND57BME23BKDCPP2UH1NB0C21HUMNGS5T71AVP6P24E0EI&code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8' https://hh.ru/oauth/token 

In response, you will get a json containing a token (the access_token field):

 { "access_token": "VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB47BBCMQ1", "token_type": "bearer", "expires_in": 1209599, "refresh_token": "OARLQNLT6JSMDI88CO5QIP35OOSQUTOO9IQNT20MOMAHE4H8SGPM7LQUAP8EO1G6" } 

It's all. Further, by executing requests in the API with the Authorization: Bearer your_access_token header, you will perform actions from under the user. To avoid authorization for each request, save access_token.

For example, here’s a request for a list of current user’s resumes:

 curl -k -H 'Authorization: Bearer VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB21BBCMQ1' -H 'User-Agent: api-test-agent' https://api.hh.ru/resumes/mine 

It should be noted that the token has a lifetime specified in the expires_in field, after which it has to be updated .

API is constantly growing, it is implemented more and more new features. If you strongly lack some functionality, have any suggestions or have found an error, then write us to the issues on the githaba.