Web APIの使用方法

URLフォーマット

以下はWeb APIリクエストを作成するための構文です。:

Example WEB API URL

https://api.sendgrid.com/api/[module].[action].[format]

  • [module] - APIのエンドポイントです。
  • [action] - 各モジュールは複数のアクションをサポートしています。add, get, deleteなどです。
  • [format] - 応答フォーマットを決定します。JSONの場合”json”、XMLの場合”xml”が利用可能です。
1
https://api.sendgrid.com/api/blocks.get.json

応答

HTTP応答コード

  • 2XX - APIコールが成功
  • 4XX - APIコールのパラメータにエラーがあります。応答のBodyにエラーの内容が含まれます。
  • 5XX - APIコールが失敗しました。時間をおいてリトライしてください。

応答の形式はXMLとJSONをサポートしています。失敗および成功時の応答を以下に示します。

失敗時

  • XML
    1
    2
    3
    4
    5
    6
    7
    8
    
    <result>
       <message>error</message>
       <errors>
          ...
          <error>... error messages ...</error>
          ...
       </errors>
    </result>
    
  • JSON
    1
    2
    3
    4
    5
    6
    
    {
      "message": "error",
      "errors": [
        "...error messages..."
      ]
    }
    

成功時


認証

APIコールには認証が必要です。APIコールの際、以下のHTTPパラメータを送信する必要があります。認証情報はSMTP認証およびWebサイトと同じです。

  • api_user - SMTPおよびWebサイトの認証設定と同じです。
  • api_key - SMTPおよびWebサイトのパスワードと同じです。

ユーザ名とパスワード付きのAPI URLの例

1
https://api.sendgrid.com/api/blocks.get.json?api_user=your_sendgrid_username&api_key=your_sendgrid_password

各APIの詳細については各APIの章を参照してください。

データのエンコード

GETリクエストを利用する場合、通常クエリストリングでデータを送信することを意味します。クエリストリングはURLの’?’以降の部分のキー/値のペアです。キーはデータを送信する場所で定義されておりURLセーフですが、値はURLセーフとは限りません。 URLで送信する全ての情報はURLエンコードが必要です。

例えば、google.comに対して”sendgrid.com/docs/”という値のクエリを送信する場合以下のようなURLになります:

1
https://www.google.com/?gws_rd=ssl#q=sendgrid.com%2Fdocs%2F

ここで “sendgrid.com/docs/” は “sendgrid.com%2Fdocs%2F” にエンコードされました。

ほとんどのプログラミング言語はURLエンコードをサポートしています。詳しくは各言語のリファレンスを参照してください。また、Wikipediaも参照してください。