Geekly Articles each Day
📜 ⬆️ ⬇️

Migrating to a new version of API

Moving the Mote-Morris House: Leesburg, Florida

The lifetime of the first version of our API comes to an end. For those who have not yet transferred their applications to the new version, we have prepared a migration guide.

The thing that probably strikes you is that there is no XML in the new version. Yes, we left only JSON, but this is not all.

REST

When designing the API, we followed the REST approach in naming URLs and using the capabilities of the HTTP protocol.
')
In short, in the responses 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 must be able to handle them correctly: do not make senseless repetitions at 429 and / or 400 and not fall from receiving 503.

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

Now, to perform a job search instead of contacting /1/json/vacancy/search/ , the address of the Vacancy collection has appeared: /vacancies .

By making a GET request to this address, you can get both a complete collection (all vacancies on the site) and a slice by specifying the query parameters: GET /vacancies?text= . By specifying the `text` parameter, we applied a filter to the collection and thus obtained search results for jobs.

The full list of parameters is available in the documentation section of the same name .

You can get a separate element of the collection, in this case a vacancy: GET /vacancies/7760476 .

A collection resource may also have subcollections, some pre-installed sections of the entire collection. GET /vacancies/favorited will return those jobs that have been added from an authorized user to “selected”.

To add a vacancy to the "selected", you must add a vacancy to the appropriate subcollection:
PUT /vacancies/favorited/{vacancy_id}


To remove, you must remove it from this collection.
DELETE /vacancies/favorited/{vacancy_id}


PUT and DELETE requests are idempotent: if you try to “select” a job that is already in the selected ones, PUT will return 204, thereby answering: “Do you want this job to be in the selected ones? No problem. She's selected. ” Even if she was already there. Also with the removal.

To create a vacancy (this functionality has not yet been implemented, but is planned), you will need to make a POST /vacancies , specifying the parameters of the vacancy created in the body. The main difference between POST and PUT is that the first one is not idempotent, that is, if you re-request, you will attempt to create another vacancy.

In summary: the correct and widespread use of HTTP methods, HTTP codes and URL naming in accordance with the concepts: collection, subcollection and element of the collection - in our understanding 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. The numbering comes from zero, the default is the first (zero) page with 20 objects on the page.

Versionality

We removed versioning, the API now has no prefix in the address: /1/... All URLs come from the root: api.hh.ru/dictionaries api.hh.ru/dictionaries . Over time, the data will expand, always providing backward compatibility. Exceptions to this rule can be only in two cases:


Less "hardcode"

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

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


Having received the search results, you do not need to construct a link yourself to get complete information about the job, you just need to take the value of the url key.

Search and view jobs

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

To search, you need to make a GET request to the resource, passing the necessary query parameters. To obtain 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 of a specific company, now it is available through a search: GET /vacancies?employer_id=1455 https://api.hh.ru/vacancies?employer_id=1455

Directories

To make a request to search, as well as to understand the answers, we give out reference books of our entities: type of employment, work schedule, currency, work experience. Previously, it was available at separate addresses:

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

We left separate reference books containing a large number of values ​​( specializations , regions , subways ) to separate addresses:

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

Authorization and new services


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

Source: https://habr.com/ru/post/201202/

More articles:


All Articles