はてなブログoEmbed API
概要
本ドキュメントは、はてなブログにおけるoEmbed実装を解説するものです。
oEmbedとは
oEmbedは、Webサイトにさまざまなコンテンツを埋め込むための仕組みで、各Webサービスのプロパイダによって提供されます。現在、はてなでは、はてなブログの各記事をoEmbedを用いて埋め込むことが可能です。oEmbedの詳細についてはoembed.com(英語)をご覧ください。
詳細説明
エンドポイント
エンドポイントは以下に定義しています。
http://hatenablog.com/oembed
このエンドポイントにいくつかのパラメータを加えてGETリクエストを送ることで、JSON形式もしくはXML形式でデータを取得することができます。エンコーディングはUTF-8です。
| パラメータ | デフォルト | 解説 |
|---|---|---|
| url | - | 参照したい記事のパーマリンクを指定する |
| format | json | (オプション) データの形式を指定する(jsonもしくはxml) |
なお、ブログの公開範囲が「すべての人に公開」に設定されている記事についてのみ、データを取得できます。プライベートなブログなどに対して、情報を参照することはできません。
リクエスト(JSON)
$ curl -X GET http://hatenablog.com/oembed -d 'url=http://staff.hatenablog.com/entry/2014/08/29/141633' -d 'format=json'
http://hatenablog.com/oembed?url=http://staff.hatenablog.com/entry/2014/08/29/141633&format=json
レスポンス(JSON)
{
"author_name": "hatenablog",
"width": "100%",
"author_url": "http://blog.hatena.ne.jp/hatenablog/",
"provider_url": "http://hatenablog.com",
"version": "1.0",
"provider_name": "Hatena Blog",
"height": "190",
"html": "<iframe src=\"http://staff.hatenablog.com/embed/2014/08/29/141633\" title=\"はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます - はてなブログ開発ブログ\" scrolling=\"no\" frameborder=\"0\" style=\"width: 100%; height: 190px; max-width: 500px; margin: 10px 0px;\"><a href=\"http://staff.hatenablog.com/entry/2014/08/29/141633\">はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます - はてなブログ開発ブログ</a></iframe>",
"url": "http://staff.hatenablog.com/entry/2014/08/29/141633",
"title": "はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます",
"type": "rich"
}
リクエスト(XML)
$ curl -X GET http://hatenablog.com/oembed -d 'url=http://staff.hatenablog.com/entry/2014/08/29/141633' -d 'format=xml'
http://hatenablog.com/oembed?url=http://staff.hatenablog.com/entry/2014/08/29/141633&format=xml
レスポンス(XML)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
<author_name>hatenablog</author_name>
<author_url>http://blog.hatena.ne.jp/hatenablog/</author_url>
<height>190</height>
<html><iframe src="http://staff.hatenablog.com/embed/2014/08/29/141633" title="はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます - はてなブログ開発ブログ" scrolling="no" frameborder="0" style="width: 100%; height: 190px; max-width: 500px; margin: 10px 0px;"><a href="http://staff.hatenablog.com/entry/2014/08/29/141633">はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます - はてなブログ開発ブログ</a></iframe></html>
<provider_name>Hatena Blog</provider_name>
<provider_url>http://hatenablog.com</provider_url>
<title>はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます</title>
<type>rich</type>
<url>http://staff.hatenablog.com/entry/2014/08/29/141633</url>
<version>1.0</version>
<width>100%</width>
</oembed>
エラー
間違ったリクエストや閲覧権限がない場合、APIがエラーを返すことがあります。
| エラーコード | 主なエラー |
|---|---|
| 404 | 記事やブログが見つからない |
| 401 | ブログの公開範囲が「すべての人に公開」ではない |
| 400 | 指定されたパラメータが正当でない |
Discovery
oEmbedの仕様では、head内にある要素を埋め込むことで、そのWebサイトがoEmbedに対応していることを示すことができます。はてなブログoEmbedもこの仕様に準拠しており、APIのエンドポイントをここから得ることもできます。具体的には以下の要素が埋め込まれています。
<link rel="alternate" type="application/json+oembed"
href="http://hatenablog.com/oembed?url=http%3A%2F%2Fblog.hatenablog.com%2Fentry%2Fabout&format=json"
title="oEmbed Profile of 「週刊はてなブログ」について" />
<link rel="alternate" type="text/xml+oembed"
href="http://hatenablog.com/oembed?url=http%3A%2F%2Fblog.hatenablog.com%2Fentry%2Fabout&format=xml"
title="oEmbed Profile of 「週刊はてなブログ」について" />
参考文章
- oembed.com(英語)
変更履歴
- 2014年9月3日 リリース
- 2020年11月10日 指定されたパラメータが正当でない場合のエラーコードを501から400に変更