Migration to a new version of the API

    Moving the Mote-Morris House: Leesburg, Florida

    The lifetime of the first version of our API is drawing to a close . For those who have not yet migrated their applications to the new version, we have prepared a migration guide.

    The most striking thing is that the new version does not have XML. Yes, we left only JSON, but that is not all.


    When designing the API, we followed the REST approach in naming URLs and using the capabilities of the HTTP protocol.

    In short, in the answers of our API, in addition to the standard 200, 302, 403, 404 and 500 statuses, you can see: 201, 204, 405, 429, 503 and some others. The API client should be able to correctly process them: do not make senseless repetitions at 429 and / or 400 and do not fall from receiving 503.

    When naming URLs, we used the terms “collection” and “collection element”, and we express actions directly using HTTP methods.

    Now search for the vacancies instead of accessing /1/json/vacancy/search/appeared address collection "Jobs": /vacancies.

    Making a GET-request at this address, you can get as a complete collection (all the jobs on the site), and some slice specifying query-parameters: GET /vacancies?text=голова. By specifying the `text` parameter, we applied the filter to the collection and thereby received the search results for vacancies.

    A complete list of parameters is available in the documentation section of the same name .

    A separate item in the collection, in this case the vacancy: GET /vacancies/7760476.

    A collection resource can also have subcollections, some predefined slices of the entire collection. GET /vacancies/favoritedwill return those vacancies that are added by an authorized user to the "selected" ones.

    To add a vacancy to the “selected”, you need to add a vacancy to the appropriate subcollection:
    PUT /vacancies/favorited/{vacancy_id}

    To remove, you must remove it from this collection. PUT and DELETE requests are idempotent: if you try to “select” a vacancy that is already in the selected ones, PUT will return 204, thereby answering: “Do you want this vacancy to be selected? No problem. She's selected. ” Even if she was already there. Also with deletion. In order to create a vacancy (this functionality has not yet been implemented, but is planned), it will be necessary to make a request indicating the parameters of the created vacancy in the body. The main difference between POST and PUT is that the first is not idempotent, that is, when you re-request, there will be an attempt to create another vacancy. Eventually:
    DELETE /vacancies/favorited/{vacancy_id}

    POST /vacancies

    the correct and widespread use of HTTP methods, HTTP codes and naming URLs in accordance with the concepts: collection, subcollection and collection element - in our understanding, there is REST.

    Pagination and collections

    A little more about the collection. All collections that support pagination (resumes, vacancies, companies and all their subcollections) look uniform and have a root object of the form:

      "found": 0,
      "per_page": 20,
      "page": 0,
      "pages": 1,
      "items": []

    For any collection request, you can specify page = N & per_page = M in the parameters. Numbering starts from scratch, by default, the first (zero) page is issued with 20 objects per page.


    We have removed versioning, in the API are now no prefix in the address: /1/.... All come from the root URL: api.hh.ru/dictionaries. Over time, data will expand, always providing backward compatibility. There can be exceptions to this rule only in two cases:
    • correction of a critical defect: an error will creep into the release, or maybe even into the published documentation, correcting which we will have to change the data format.
    • closing the API due to a change in business logic: hh.ru will cease to provide a vacancy database, we will disappear responses on the site as a service and other incredible, fantastic cases when we theoretically cannot support the format of the output data.

    Less hardcode

    In the place where we give out the value that represents the entity that is available in our API, we provide a full link to save you from the need to “hardcode” the addresses in your application.
    For example, in a job search:

      "items": [
          "url": "https://api.hh.ru/vacancies/1337"

    Having received the search results, you don’t need to construct a link yourself to get full information about the vacancy, you just need to take the key value url.

    Search and view vacancies

    Now about the data itself. The main and most popular use of our API is the search and delivery of vacancies.
    Previously, it was available at addresses /1/json/vacancy/search/and, /1/json/vacancy/{vacancy_id}accordingly. Now, following the REST approach, we have combined this into the / vacancies collection .

    To search, you need to make a GET request to the resource by passing the necessary query parameters. To receive a separate vacancy, make a GET request for a separate element: GET /vacancies/7760476( https://api.hh.ru/vacancies/7760476 .

    We also used to have a separate address for receiving vacancies for a particular company, now it is available through a search: GET /vacancies?employer_id=1455https: / /api.hh.ru/vacancies?employer_id=1455


    To carry out a search request, as well as to understand the answers, we issue directories of our entities: type of employment, work schedule, currency, work experience. It used to be available at individual addresses:
    • GET /1/json/employment/
    • GET /1/json/schedule/
    • GET /1/json/experience/
    • GET /1/json/currency/

    Now we have combined all these small reference books into one `/dictionaries`api.hh.ru/dictionaries resource . (description in documentation: github.com/hhru/api/blob/master/docs/dictionaries.md ). We left

    separate directories containing a large number of meanings ( specializations , regions , metro ) at separate addresses:

    Specializations were combined with professional areas (previously it was two different addresses: field and specialization).
    The regions were renamed to /areas- api.hh.ru/areas .

    Authorization and new services

    But the HeadHunter API is not limited to job searches and related directories. In the new version, authorization , viewing responses and much more are available. This is beyond the scope of the article on migration, but a description of all these methods is available in our documentation . Read, try, write to us, stay tuned!

    Also popular now: