hh.ruにはオープンAPIがあることを知っている人もいると思います（これについてはこことここで説明しました ）。これは私たちだけでなく、サードパーティの開発者によっても使用されています。 たとえば、その助けを借りて、大量の関連データで市場を非常に徹底的に分析できます。



一連の2つの記事を考案しました。この記事では、APIの使用を迅速かつ簡単に開始する方法を示し、 次では、履歴書の現在の空き状況を推奨する小さなプロジェクトを行います。



まず、APIの一般的な機能、使用場所、使用方法について簡単に説明します。

API機能

APIの機能をすばやく把握するには、たとえば、申請者（ Android 、 iOS ）および雇用主（ Android 、 iOS ） 向けのモバイルアプリケーションに注意を払ってください。 APIを介して動作します。



たとえば、外部の開発者は、給与やその他の詳細とともに、関連するすべての空席を受け取ることができます。 そして、これはほぼ40万人のライブ空席であり、地獄はどれだけ多くのアーカイブ空席を知っています。 市場を分析したい人は、たくさんの実際のデータで遊んでください-あなたはここにいます。



APIを介して、求人検索が機能します。 サイトで使用される地域、労働者の専門分野、産業部門、地下鉄駅など、さまざまなディレクトリが利用可能です。 承認されたユーザーの場合、求人または求職者かどうかに応じて、求人または履歴書を利用できます。 雇用主にとっては、求人と求職の機会があります。



詳細については、 ドキュメントを参照してください。

APIはどのように機能しますか？

RESTの最良の伝統では、HTTPSプロトコルに関してすべての対話が行われます。 GETリクエストを行い、削除-DELETE、作成-POST、編集-PUTを行います。 データはJSON形式で交換されます。 一部の操作は許可なく使用できますが、他の操作は使用できません。 許可されたユーザーは、雇用主または求職者として行動できます。 彼が利用できる方法に依存します。 OAuth2プロトコルは認証に使用されます（これを行う方法については、以下の指で説明します）。 あなたは私たちのサイトのどれかからデータを扱うことができます 。 ドキュメントの「 一般情報 」セクションの詳細。

はじめに

許可なしに利用可能なデータの操作を開始するために、何も必要ありません。 ドキュメントでどのメソッドを使用できるかを調べ、リクエストを行います-データを取得します。 たとえば、空席を表示する場合

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

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

User-Agentヘッダーを渡す必要があることに注意してください。 彼なしでは機能しません。



空室を検索するには、さまざまなパラメータを設定できます 。

したがって、たとえば、モスクワのAlekseevskaya地下鉄駅で、Javaキーワードで空室を検索できます。

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

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

areaおよびmetroの値は、ディレクトリから取得できます。

ログイン

すでに述べたように、OAuth2プロトコルは認証に使用されます。

ユーザーの下で何かを行うには、ユーザーはトークンを受け取り、要求されたときにこのトークンをヘッダーに渡す必要があります。 ユーザーのトークンを取得するには、APIでトークンを生成するだけで十分です。 https://dev.hh.ruの個人アカウントにアクセスし、「トークンの生成」ボタンをクリックします。



他のユーザーがアプリケーションでアクションを実行できるように、このアプリケーションは最初に個人アカウントで開始する必要があります。 リダイレクトURIを指定してアプリケーションを追加します。 ユーザーは承認後にこのアドレスに自動的に戻ります。



アプリケーションを追加すると、クライアントIDとクライアントシークレットが割り当てられます。

認証はどのように機能しますか？

アプリケーションでは、アプリケーションのクライアントIDを示す承認リンクを配置します。たとえば、

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

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ユーザーがこのリンクをクリックすると、私たちの側で特別なコードが生成されます。 そして、当社のサイトはユーザーをアプリケーションにリダイレクトし（アプリケーションの登録時に指定されたリダイレクトURIによって）、コードを含むパラメーターをアプリケーションのアドレスに追加します。 例：

 http://yourapphost/?code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

その後、このアドレスからコードを引き出し、それを使用してAPIにPOSTリクエストを送信し、コード、client_idおよび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
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

応答として、トークンを含むjsonを取得します（access_tokenフィールド）：

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

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

以上です。 さらに、Authorization：Bearer your_access_tokenというタイトルのAPIでリクエストを実行することにより、ユーザーの下からアクションを実行します。 各リクエストの承認を防ぐには、access_tokenを自分の場所に保管してください。



たとえば、現在のユーザーの履歴書リストを取得するクエリは次のとおりです。

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

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

トークンの有効期限はexpires_inフィールドで指定されており、その後はトークンを更新する必要があることに注意してください。



APIは常に成長しており、ますます多くの新機能を実装しています。 機能が本当に不足している場合、何か提案がある場合、または間違いを見つけた場合は、githubで問題を報告してください。