Created
May 16, 2017 02:51
-
-
Save muziyoshiz/80d5269d9a6aaaee43c4517b736e1136 to your computer and use it in GitHub Desktop.
Sample of API Blueprint document
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
FORMAT: 1A | |
# Sample API | |
## Sample API について | |
Sample API は、与えられた URL にアクセスしたオーディエンスに対するレコメンド記事を返す、架空の API である。 | |
## API 共通のエラー形式 | |
### クライアント側が原因の場合 | |
400 Bad Request を返す。ボディ部は以下の形式とする。 | |
``` | |
{"message":"エラーメッセージ"} | |
``` | |
全APIに共通のエラーメッセージとして、以下を定義する。 | |
| エラーメッセージ | 意味 | | |
|:----------------|:-----| | |
| Missing parameters | 必須(required)のパラメータが1個以上指定されていない | | |
| Invalid parameters | 必須のパラメータが指定されているが、1個以上のパラメータの形式が間違っている | | |
| Invalid contract | 指定された契約IDに対応する契約が存在しない | | |
### サーバ側が原因の場合 | |
500 Internal Server Error を返す。ボディ部は以下の形式とする。 | |
``` | |
{"message":"エラーメッセージ"} | |
``` | |
全APIに共通のエラーメッセージとして、以下を定義する。 | |
| エラーメッセージ | 意味 | | |
|:----------------|:-----| | |
| Server busy | サーバ内の処理がタイムアウトした場合 | | |
| Server failure | タイムアウト以外の問題で、例外が発生した場合 | | |
# Group レコメンド | |
## レコメンド記事のエンドポイント [/api/v1/articles?contract={contract}&url={url}&audience={audience}&dnt={dnt}] | |
### レコメンド記事の取得 [GET] | |
#### 概要 | |
* レコメンド記事を取得したい場合に、この API を呼び出す。 | |
+ Parameters | |
+ contract: 1000 (number, required) - 契約 ID | |
+ url: `http%3A%2F%2Ftechblog.gmo-ap.jp%2Fapi-blueprint` (string, required) - 記事のレコメンドに使いたい URL | |
+ audience: abcdefghijklmnopqrstuvwxyz (string, required) - オーディエンスの特定に用いる ID | |
+ dnt: 0 (enum[number], optional) - オーディエンス ID をターゲティング利用するかどうか | |
ターゲティング利用を許可する場合は 0、しない場合は 1 | |
+ Default: 0 | |
+ Members | |
+ 0 | |
+ 1 | |
+ Request (application/json) | |
+ Headers | |
Accept: application/json | |
+ Response 200 (application/json) | |
* リクエストが正常に処理された場合。 | |
* 配列中の並び順は、レコメンド順序を表す。優先度の一番高い記事が先頭。 | |
* レコメンド結果が存在しない場合は、"articles" の値として、空の配列が返される。 | |
+ Attributes | |
+ articles (array[Article], required) - レコメンド記事を優先度の高い順に並べた配列 | |
+ Response 400 (application/json) | |
+ Attributes | |
+ message: Missing parameters (enum[string], required) - エラーメッセージ | |
+ Members | |
+ Missing parameters | |
+ Invalid parameters | |
+ Invalid contract | |
+ Response 500 (application/json) | |
+ Attributes | |
+ message: Server busy (enum[string], required) - エラーメッセージ | |
+ Members | |
+ Server busy | |
+ Server failure | |
# Data Structures | |
## Article (object) | |
+ title: `API Blueprint で API 仕様書を書いて、配布用の HTML を自動生成する方法` (string, required) - レコメンドされた記事のタイトル | |
+ url: `http://techblog.gmo-ap.jp/api-blueprint` (string, required) - レコメンドされた記事のURL(測定用パラメータ付きURL) | |
+ publishedAt: `2017-05-24T17:44:06+09:00` (string) - レコメンドされた記事の公開日 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<!DOCTYPE html><html><head><meta charset="utf-8"><title>Sample API</title><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css"><style>@import url('https://fonts.googleapis.com/css?family=Roboto:400,700|Inconsolata|Raleway:200');.hljs-comment,.hljs-title{color:#8e908c}.hljs-variable,.hljs-attribute,.hljs-tag,.hljs-regexp,.ruby .hljs-constant,.xml .hljs-tag .hljs-title,.xml .hljs-pi,.xml .hljs-doctype,.html .hljs-doctype,.css .hljs-id,.css .hljs-class,.css .hljs-pseudo{color:#c82829}.hljs-number,.hljs-preprocessor,.hljs-pragma,.hljs-built_in,.hljs-literal,.hljs-params,.hljs-constant{color:#f5871f}.ruby .hljs-class .hljs-title,.css .hljs-rules .hljs-attribute{color:#eab700}.hljs-string,.hljs-value,.hljs-inheritance,.hljs-header,.ruby .hljs-symbol,.xml .hljs-cdata{color:#718c00}.css .hljs-hexcolor{color:#3e999f}.hljs-function,.python .hljs-decorator,.python .hljs-title,.ruby .hljs-function .hljs-title,.ruby .hljs-title .hljs-keyword,.perl .hljs-sub,.javascript .hljs-title,.coffeescript .hljs-title{color:#4271ae}.hljs-keyword,.javascript .hljs-function{color:#8959a8}.hljs{display:block;background:white;color:#4d4d4c;padding:.5em}.coffeescript .javascript,.javascript .xml,.tex .hljs-formula,.xml .javascript,.xml .vbscript,.xml .css,.xml .hljs-cdata{opacity:.5}.right .hljs-comment{color:#969896}.right .css .hljs-class,.right .css .hljs-id,.right .css .hljs-pseudo,.right .hljs-attribute,.right .hljs-regexp,.right .hljs-tag,.right .hljs-variable,.right .html .hljs-doctype,.right .ruby .hljs-constant,.right .xml .hljs-doctype,.right .xml .hljs-pi,.right .xml .hljs-tag .hljs-title{color:#c66}.right .hljs-built_in,.right .hljs-constant,.right .hljs-literal,.right .hljs-number,.right .hljs-params,.right .hljs-pragma,.right .hljs-preprocessor{color:#de935f}.right .css .hljs-rule .hljs-attribute,.right .ruby .hljs-class .hljs-title{color:#f0c674}.right .hljs-header,.right .hljs-inheritance,.right .hljs-name,.right .hljs-string,.right .hljs-value,.right .ruby .hljs-symbol,.right .xml .hljs-cdata{color:#b5bd68}.right .css .hljs-hexcolor,.right .hljs-title{color:#8abeb7}.right .coffeescript .hljs-title,.right .hljs-function,.right .javascript .hljs-title,.right .perl .hljs-sub,.right .python .hljs-decorator,.right .python .hljs-title,.right .ruby .hljs-function .hljs-title,.right .ruby .hljs-title .hljs-keyword{color:#81a2be}.right .hljs-keyword,.right .javascript .hljs-function{color:#b294bb}.right .hljs{display:block;overflow-x:auto;background:#1d1f21;color:#c5c8c6;padding:.5em;-webkit-text-size-adjust:none}.right .coffeescript .javascript,.right .javascript .xml,.right .tex .hljs-formula,.right .xml .css,.right .xml .hljs-cdata,.right .xml .javascript,.right .xml .vbscript{opacity:.5}body{color:black;background:white;font:400 14px / 1.42 'Roboto',Helvetica,sans-serif}header{border-bottom:1px solid #f2f2f2;margin-bottom:12px}h1,h2,h3,h4,h5{color:black;margin:12px 0}h1 .permalink,h2 .permalink,h3 .permalink,h4 .permalink,h5 .permalink{margin-left:0;opacity:0;transition:opacity .25s ease}h1:hover .permalink,h2:hover .permalink,h3:hover .permalink,h4:hover .permalink,h5:hover .permalink{opacity:1}.triple h1 .permalink,.triple h2 .permalink,.triple h3 .permalink,.triple h4 .permalink,.triple h5 .permalink{opacity:.15}.triple h1:hover .permalink,.triple h2:hover .permalink,.triple h3:hover .permalink,.triple h4:hover .permalink,.triple h5:hover .permalink{opacity:.15}h1{font:200 36px 'Raleway',Helvetica,sans-serif;font-size:36px}h2{font:200 36px 'Raleway',Helvetica,sans-serif;font-size:30px}h3{font-size:100%;text-transform:uppercase}h5{font-size:100%;font-weight:normal}p{margin:0 0 10px}p.choices{line-height:1.6}a{color:#428bca;text-decoration:none}li p{margin:0}hr.split{border:0;height:1px;width:100%;padding-left:6px;margin:12px auto;background-image:linear-gradient(to right, rgba(0,0,0,0) 20%, rgba(0,0,0,0.2) 51.4%, rgba(255,255,255,0.2) 51.4%, rgba(255,255,255,0) 80%)}dl dt{float:left;width:130px;clear:left;text-align:right;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:700}dl dd{margin-left:150px}blockquote{color:rgba(0,0,0,0.5);font-size:15.5px;padding:10px 20px;margin:12px 0;border-left:5px solid #e8e8e8}blockquote p:last-child{margin-bottom:0}pre{background-color:#f5f5f5;padding:12px;border:1px solid #cfcfcf;border-radius:6px;overflow:auto}pre code{color:black;background-color:transparent;padding:0;border:none}code{color:#444;background-color:#f5f5f5;font:'Inconsolata',monospace;padding:1px 4px;border:1px solid #cfcfcf;border-radius:3px}ul,ol{padding-left:2em}table{border-collapse:collapse;border-spacing:0;margin-bottom:12px}table tr:nth-child(2n){background-color:#fafafa}table th,table td{padding:6px 12px;border:1px solid #e6e6e6}.text-muted{opacity:.5}.note,.warning{padding:.3em 1em;margin:1em 0;border-radius:2px;font-size:90%}.note h1,.warning h1,.note h2,.warning h2,.note h3,.warning h3,.note h4,.warning h4,.note h5,.warning h5,.note h6,.warning h6{font-family:200 36px 'Raleway',Helvetica,sans-serif;font-size:135%;font-weight:500}.note p,.warning p{margin:.5em 0}.note{color:black;background-color:#f0f6fb;border-left:4px solid #428bca}.note h1,.note h2,.note h3,.note h4,.note h5,.note h6{color:#428bca}.warning{color:black;background-color:#fbf1f0;border-left:4px solid #c9302c}.warning h1,.warning h2,.warning h3,.warning h4,.warning h5,.warning h6{color:#c9302c}header{margin-top:24px}nav{position:fixed;top:24px;bottom:0;overflow-y:auto}nav .resource-group{padding:0}nav .resource-group .heading{position:relative}nav .resource-group .heading .chevron{position:absolute;top:12px;right:12px;opacity:.5}nav .resource-group .heading a{display:block;color:black;opacity:.7;border-left:2px solid transparent;margin:0}nav .resource-group .heading a:hover{text-decoration:none;background-color:bad-color;border-left:2px solid black}nav ul{list-style-type:none;padding-left:0}nav ul a{display:block;font-size:13px;color:rgba(0,0,0,0.7);padding:8px 12px;border-top:1px solid #d9d9d9;border-left:2px solid transparent;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}nav ul a:hover{text-decoration:none;background-color:bad-color;border-left:2px solid black}nav ul>li{margin:0}nav ul>li:first-child{margin-top:-12px}nav ul>li:last-child{margin-bottom:-12px}nav ul ul a{padding-left:24px}nav ul ul li{margin:0}nav ul ul li:first-child{margin-top:0}nav ul ul li:last-child{margin-bottom:0}nav>div>div>ul>li:first-child>a{border-top:none}.preload *{transition:none !important}.pull-left{float:left}.pull-right{float:right}.badge{display:inline-block;float:right;min-width:10px;min-height:14px;padding:3px 7px;font-size:12px;color:#000;background-color:#f2f2f2;border-radius:10px;margin:-2px 0}.badge.get{color:#70bbe1;background-color:#d9edf7}.badge.head{color:#70bbe1;background-color:#d9edf7}.badge.options{color:#70bbe1;background-color:#d9edf7}.badge.put{color:#f0db70;background-color:#fcf8e3}.badge.patch{color:#f0db70;background-color:#fcf8e3}.badge.post{color:#93cd7c;background-color:#dff0d8}.badge.delete{color:#ce8383;background-color:#f2dede}.collapse-button{float:right}.collapse-button .close{display:none;color:#428bca;cursor:pointer}.collapse-button .open{color:#428bca;cursor:pointer}.collapse-button.show .close{display:inline}.collapse-button.show .open{display:none}.collapse-content{max-height:0;overflow:hidden;transition:max-height .3s ease-in-out}nav{width:220px}.container{max-width:940px;margin-left:auto;margin-right:auto}.container .row .content{margin-left:244px;width:696px}.container .row:after{content:'';display:block;clear:both}.container-fluid nav{width:22%}.container-fluid .row .content{margin-left:24%}.container-fluid.triple nav{width:16.5%;padding-right:1px}.container-fluid.triple .row .content{position:relative;margin-left:16.5%;padding-left:24px}.middle:before,.middle:after{content:'';display:table}.middle:after{clear:both}.middle{box-sizing:border-box;width:51.5%;padding-right:12px}.right{box-sizing:border-box;float:right;width:48.5%;padding-left:12px}.right a{color:#428bca}.right h1,.right h2,.right h3,.right h4,.right h5,.right p,.right div{color:white}.right pre{background-color:#1d1f21;border:1px solid #1d1f21}.right pre code{color:#c5c8c6}.right .description{margin-top:12px}.triple .resource-heading{font-size:125%}.definition{margin-top:12px;margin-bottom:12px}.definition .method{font-weight:bold}.definition .method.get{color:#2e8ab8}.definition .method.head{color:#2e8ab8}.definition .method.options{color:#2e8ab8}.definition .method.post{color:#56b82e}.definition .method.put{color:#b8a22e}.definition .method.patch{color:#b8a22e}.definition .method.delete{color:#b82e2e}.definition .uri{word-break:break-all;word-wrap:break-word}.definition .hostname{opacity:.5}.example-names{background-color:#eee;padding:12px;border-radius:6px}.example-names .tab-button{cursor:pointer;color:black;border:1px solid #ddd;padding:6px;margin-left:12px}.example-names .tab-button.active{background-color:#d5d5d5}.right .example-names{background-color:#444}.right .example-names .tab-button{color:white;border:1px solid #666;border-radius:6px}.right .example-names .tab-button.active{background-color:#5e5e5e}#nav-background{position:fixed;left:0;top:0;bottom:0;width:16.5%;padding-right:14.4px;background-color:#fbfbfb;border-right:1px solid #f0f0f0;z-index:-1}#right-panel-background{position:absolute;right:-12px;top:-12px;bottom:-12px;width:48.6%;background-color:#333;z-index:-1}@media (max-width:1200px){nav{width:198px}.container{max-width:840px}.container .row .content{margin-left:224px;width:606px}}@media (max-width:992px){nav{width:169.4px}.container{max-width:720px}.container .row .content{margin-left:194px;width:526px}}@media (max-width:768px){nav{display:none}.container{width:95%;max-width:none}.container .row .content,.container-fluid .row .content,.container-fluid.triple .row .content{margin-left:auto;margin-right:auto;width:95%}#nav-background{display:none}#right-panel-background{width:48.6%}}.back-to-top{position:fixed;z-index:1;bottom:0;right:24px;padding:4px 8px;color:rgba(0,0,0,0.5);background-color:#f2f2f2;text-decoration:none !important;border-top:1px solid #d9d9d9;border-left:1px solid #d9d9d9;border-right:1px solid #d9d9d9;border-top-left-radius:3px;border-top-right-radius:3px}.resource-group{padding:12px;margin-bottom:12px;background-color:white;border:1px solid #d9d9d9;border-radius:6px}.resource-group h2.group-heading,.resource-group .heading a{padding:12px;margin:-12px -12px 12px -12px;background-color:#f2f2f2;border-bottom:1px solid #d9d9d9;border-top-left-radius:6px;border-top-right-radius:6px;white-space:nowrap;text-overflow:ellipsis;overflow:hidden}.triple .content .resource-group{padding:0;border:none}.triple .content .resource-group h2.group-heading,.triple .content .resource-group .heading a{margin:0 0 12px 0;border:1px solid #d9d9d9}nav .resource-group .heading a{padding:12px;margin-bottom:0}nav .resource-group .collapse-content{padding:0}.action{margin-bottom:12px;padding:12px 12px 0 12px;overflow:hidden;border:1px solid transparent;border-radius:6px}.action h4.action-heading{padding:6px 12px;margin:-12px -12px 12px -12px;border-bottom:1px solid transparent;border-top-left-radius:6px;border-top-right-radius:6px;overflow:hidden}.action h4.action-heading .name{float:right;font-weight:normal;padding:6px 0}.action h4.action-heading .method{padding:6px 12px;margin-right:12px;border-radius:3px;display:inline-block}.action h4.action-heading .method.get{color:#fff;background-color:#337ab7}.action h4.action-heading .method.head{color:#fff;background-color:#337ab7}.action h4.action-heading .method.options{color:#fff;background-color:#337ab7}.action h4.action-heading .method.put{color:#fff;background-color:#ed9c28}.action h4.action-heading .method.patch{color:#fff;background-color:#ed9c28}.action h4.action-heading .method.post{color:#fff;background-color:#5cb85c}.action h4.action-heading .method.delete{color:#fff;background-color:#d9534f}.action h4.action-heading code{color:#444;background-color:#f5f5f5;border-color:#cfcfcf;font-weight:normal;word-break:break-all;display:inline-block;margin-top:2px}.action dl.inner{padding-bottom:2px}.action .title{border-bottom:1px solid white;margin:0 -12px -1px -12px;padding:12px}.action.get{border-color:#bce8f1}.action.get h4.action-heading{color:#337ab7;background:#d9edf7;border-bottom-color:#bce8f1}.action.head{border-color:#bce8f1}.action.head h4.action-heading{color:#337ab7;background:#d9edf7;border-bottom-color:#bce8f1}.action.options{border-color:#bce8f1}.action.options h4.action-heading{color:#337ab7;background:#d9edf7;border-bottom-color:#bce8f1}.action.post{border-color:#d6e9c6}.action.post h4.action-heading{color:#5cb85c;background:#dff0d8;border-bottom-color:#d6e9c6}.action.put{border-color:#faebcc}.action.put h4.action-heading{color:#ed9c28;background:#fcf8e3;border-bottom-color:#faebcc}.action.patch{border-color:#faebcc}.action.patch h4.action-heading{color:#ed9c28;background:#fcf8e3;border-bottom-color:#faebcc}.action.delete{border-color:#ebccd1}.action.delete h4.action-heading{color:#d9534f;background:#f2dede;border-bottom-color:#ebccd1}</style></head><body class="preload"><a href="#top" class="text-muted back-to-top"><i class="fa fa-toggle-up"></i> Back to top</a><div class="container"><div class="row"><nav><div class="resource-group"><div class="heading"><div class="chevron"><i class="open fa fa-angle-down"></i></div><a href="#top">Overview</a></div><div class="collapse-content"><ul><li><a href="#header-sample-api-について">Sample API について</a></li><li><a href="#header-api-共通のエラー形式">API 共通のエラー形式</a></li><li><a href="#header-クライアント側が原因の場合">クライアント側が原因の場合</a></li><li><a href="#header-サーバ側が原因の場合">サーバ側が原因の場合</a></li></ul></div></div><div class="resource-group"><div class="heading"><div class="chevron"><i class="open fa fa-angle-down"></i></div><a href="#レコメンド">レコメンド</a></div><div class="collapse-content"><ul><li><a href="#レコメンド-レコメンド記事のエンドポイント-get"><span class="badge get"><i class="fa fa-arrow-down"></i></span>レコメンド記事の取得</a></li></ul></div></div></nav><div class="content"><header><h1 id="top">Sample API</h1></header><h2 id="header-sample-api-について">Sample API について <a class="permalink" href="#header-sample-api-について" aria-hidden="true">¶</a></h2> | |
<p>Sample API は、与えられた URL にアクセスしたオーディエンスに対するレコメンド記事を返す、架空の API である。</p> | |
<h2 id="header-api-共通のエラー形式">API 共通のエラー形式 <a class="permalink" href="#header-api-共通のエラー形式" aria-hidden="true">¶</a></h2> | |
<h3 id="header-クライアント側が原因の場合">クライアント側が原因の場合 <a class="permalink" href="#header-クライアント側が原因の場合" aria-hidden="true">¶</a></h3> | |
<p>400 Bad Request を返す。ボディ部は以下の形式とする。</p> | |
<pre><code>{"<span class="hljs-attribute">message</span>":<span class="hljs-value"><span class="hljs-string">"エラーメッセージ"</span></span>}</code></pre> | |
<p>全APIに共通のエラーメッセージとして、以下を定義する。</p> | |
<table> | |
<thead> | |
<tr> | |
<th style="text-align:left">エラーメッセージ</th> | |
<th style="text-align:left">意味</th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr> | |
<td style="text-align:left">Missing parameters</td> | |
<td style="text-align:left">必須(required)のパラメータが1個以上指定されていない</td> | |
</tr> | |
<tr> | |
<td style="text-align:left">Invalid parameters</td> | |
<td style="text-align:left">必須のパラメータが指定されているが、1個以上のパラメータの形式が間違っている</td> | |
</tr> | |
<tr> | |
<td style="text-align:left">Invalid contract</td> | |
<td style="text-align:left">指定された契約IDに対応する契約が存在しない</td> | |
</tr> | |
</tbody> | |
</table> | |
<h3 id="header-サーバ側が原因の場合">サーバ側が原因の場合 <a class="permalink" href="#header-サーバ側が原因の場合" aria-hidden="true">¶</a></h3> | |
<p>500 Internal Server Error を返す。ボディ部は以下の形式とする。</p> | |
<pre><code>{"<span class="hljs-attribute">message</span>":<span class="hljs-value"><span class="hljs-string">"エラーメッセージ"</span></span>}</code></pre> | |
<p>全APIに共通のエラーメッセージとして、以下を定義する。</p> | |
<table> | |
<thead> | |
<tr> | |
<th style="text-align:left">エラーメッセージ</th> | |
<th style="text-align:left">意味</th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr> | |
<td style="text-align:left">Server busy</td> | |
<td style="text-align:left">サーバ内の処理がタイムアウトした場合</td> | |
</tr> | |
<tr> | |
<td style="text-align:left">Server failure</td> | |
<td style="text-align:left">タイムアウト以外の問題で、例外が発生した場合</td> | |
</tr> | |
</tbody> | |
</table> | |
<section id="レコメンド" class="resource-group"><h2 class="group-heading">レコメンド <a href="#レコメンド" class="permalink">¶</a></h2><div id="レコメンド-レコメンド記事のエンドポイント" class="resource"><h3 class="resource-heading">レコメンド記事のエンドポイント <a href="#レコメンド-レコメンド記事のエンドポイント" class="permalink"> ¶</a></h3><div id="レコメンド-レコメンド記事のエンドポイント-get" class="action get"><h4 class="action-heading"><div class="name">レコメンド記事の取得</div><a href="#レコメンド-レコメンド記事のエンドポイント-get" class="method get">GET</a><code class="uri">/api/v1/articles?contract={contract}&url={url}&audience={audience}&dnt={dnt}</code></h4><h4 id="header-概要">概要 <a class="permalink" href="#header-概要" aria-hidden="true">¶</a></h4> | |
<ul> | |
<li>レコメンド記事を取得したい場合に、この API を呼び出す。</li> | |
</ul> | |
<h4>Example URI</h4><div class="definition"><span class="method get">GET</span> <span class="uri"><span class="hostname"></span>/api/v1/articles?contract=<span class="hljs-attribute" title="contract">1000</span>&url=<span class="hljs-attribute" title="url">http%3A%2F%2Ftechblog.gmo-ap.jp%2Fapi-blueprint</span>&audience=<span class="hljs-attribute" title="audience">abcdefghijklmnopqrstuvwxyz</span>&dnt=<span class="hljs-attribute" title="dnt">0</span></span></div><div class="title"><strong>URI Parameters</strong><div class="collapse-button show"><span class="close">Hide</span><span class="open">Show</span></div></div><div class="collapse-content"><dl class="inner"><dt>contract</dt><dd><code>number</code> <span class="required">(required)</span> <span class="text-muted example"><strong>Example: </strong><span>1000</span></span><p>契約 ID</p> | |
</dd><dt>url</dt><dd><code>string</code> <span class="required">(required)</span> <span class="text-muted example"><strong>Example: </strong><span>http%3A%2F%2Ftechblog.gmo-ap.jp%2Fapi-blueprint</span></span><p>記事のレコメンドに使いたい URL</p> | |
</dd><dt>audience</dt><dd><code>string</code> <span class="required">(required)</span> <span class="text-muted example"><strong>Example: </strong><span>abcdefghijklmnopqrstuvwxyz</span></span><p>オーディエンスの特定に用いる ID</p> | |
</dd><dt>dnt</dt><dd><code>number</code> <span>(optional)</span> <span class="text-info default"><strong>Default: </strong><span>0</span></span> <span class="text-muted example"><strong>Example: </strong><span>0</span></span><p>オーディエンス ID をターゲティング利用するかどうか</p> | |
<p>ターゲティング利用を許可する場合は 0、しない場合は 1</p> | |
<p class="choices"><strong>Choices: </strong><code>0</code> <code>1</code> </p></dd></dl></div><div class="title"><strong>Request</strong><div class="collapse-button"><span class="close">Hide</span><span class="open">Show</span></div></div><div class="collapse-content"><div class="inner"><h5>Headers</h5><pre><code><span class="hljs-attribute">Content-Type</span>: <span class="hljs-string">application/json</span><br><span class="hljs-attribute">Accept</span>: <span class="hljs-string">application/json</span></code></pre><div style="height: 1px;"></div></div></div><div class="title"><strong>Response <code>200</code></strong><div class="collapse-button"><span class="close">Hide</span><span class="open">Show</span></div></div><div class="collapse-content"><div class="inner"><div class="description"><ul> | |
<li> | |
<p>リクエストが正常に処理された場合。</p> | |
</li> | |
<li> | |
<p>配列中の並び順は、レコメンド順序を表す。優先度の一番高い記事が先頭。</p> | |
</li> | |
<li> | |
<p>レコメンド結果が存在しない場合は、“articles” の値として、空の配列が返される。</p> | |
</li> | |
</ul> | |
</div><h5>Headers</h5><pre><code><span class="hljs-attribute">Content-Type</span>: <span class="hljs-string">application/json</span></code></pre><div style="height: 1px;"></div><h5>Body</h5><pre><code>{ | |
"<span class="hljs-attribute">articles</span>": <span class="hljs-value">[ | |
{ | |
"<span class="hljs-attribute">title</span>": <span class="hljs-value"><span class="hljs-string">"API Blueprint で API 仕様書を書いて、配布用の HTML を自動生成する方法"</span></span>, | |
"<span class="hljs-attribute">url</span>": <span class="hljs-value"><span class="hljs-string">"http://techblog.gmo-ap.jp/api-blueprint"</span></span>, | |
"<span class="hljs-attribute">publishedAt</span>": <span class="hljs-value"><span class="hljs-string">"2017-05-24T17:44:06+09:00"</span> | |
</span>} | |
] | |
</span>}</code></pre><div style="height: 1px;"></div><h5>Schema</h5><pre><code>{ | |
"<span class="hljs-attribute">$schema</span>": <span class="hljs-value"><span class="hljs-string">"http://json-schema.org/draft-04/schema#"</span></span>, | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"object"</span></span>, | |
"<span class="hljs-attribute">properties</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">articles</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"array"</span></span>, | |
"<span class="hljs-attribute">description</span>": <span class="hljs-value"><span class="hljs-string">"レコメンド記事を優先度の高い順に並べた配列"</span> | |
</span>} | |
</span>}</span>, | |
"<span class="hljs-attribute">required</span>": <span class="hljs-value">[ | |
<span class="hljs-string">"articles"</span> | |
] | |
</span>}</code></pre><div style="height: 1px;"></div></div></div><div class="title"><strong>Response <code>400</code></strong><div class="collapse-button"><span class="close">Hide</span><span class="open">Show</span></div></div><div class="collapse-content"><div class="inner"><h5>Headers</h5><pre><code><span class="hljs-attribute">Content-Type</span>: <span class="hljs-string">application/json</span></code></pre><div style="height: 1px;"></div><h5>Body</h5><pre><code>{ | |
"<span class="hljs-attribute">message</span>": <span class="hljs-value"><span class="hljs-string">"Missing parameters"</span> | |
</span>}</code></pre><div style="height: 1px;"></div><h5>Schema</h5><pre><code>{ | |
"<span class="hljs-attribute">$schema</span>": <span class="hljs-value"><span class="hljs-string">"http://json-schema.org/draft-04/schema#"</span></span>, | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"object"</span></span>, | |
"<span class="hljs-attribute">properties</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">message</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"string"</span></span>, | |
"<span class="hljs-attribute">enum</span>": <span class="hljs-value">[ | |
<span class="hljs-string">"Missing parameters"</span>, | |
<span class="hljs-string">"Invalid parameters"</span>, | |
<span class="hljs-string">"Invalid contract"</span> | |
]</span>, | |
"<span class="hljs-attribute">description</span>": <span class="hljs-value"><span class="hljs-string">"エラーメッセージ"</span> | |
</span>} | |
</span>}</span>, | |
"<span class="hljs-attribute">required</span>": <span class="hljs-value">[ | |
<span class="hljs-string">"message"</span> | |
] | |
</span>}</code></pre><div style="height: 1px;"></div></div></div><div class="title"><strong>Response <code>500</code></strong><div class="collapse-button"><span class="close">Hide</span><span class="open">Show</span></div></div><div class="collapse-content"><div class="inner"><h5>Headers</h5><pre><code><span class="hljs-attribute">Content-Type</span>: <span class="hljs-string">application/json</span></code></pre><div style="height: 1px;"></div><h5>Body</h5><pre><code>{ | |
"<span class="hljs-attribute">message</span>": <span class="hljs-value"><span class="hljs-string">"Server busy"</span> | |
</span>}</code></pre><div style="height: 1px;"></div><h5>Schema</h5><pre><code>{ | |
"<span class="hljs-attribute">$schema</span>": <span class="hljs-value"><span class="hljs-string">"http://json-schema.org/draft-04/schema#"</span></span>, | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"object"</span></span>, | |
"<span class="hljs-attribute">properties</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">message</span>": <span class="hljs-value">{ | |
"<span class="hljs-attribute">type</span>": <span class="hljs-value"><span class="hljs-string">"string"</span></span>, | |
"<span class="hljs-attribute">enum</span>": <span class="hljs-value">[ | |
<span class="hljs-string">"Server busy"</span>, | |
<span class="hljs-string">"Server failure"</span> | |
]</span>, | |
"<span class="hljs-attribute">description</span>": <span class="hljs-value"><span class="hljs-string">"エラーメッセージ"</span> | |
</span>} | |
</span>}</span>, | |
"<span class="hljs-attribute">required</span>": <span class="hljs-value">[ | |
<span class="hljs-string">"message"</span> | |
] | |
</span>}</code></pre><div style="height: 1px;"></div></div></div></div></div></section></div></div></div><p style="text-align: center;" class="text-muted">Generated by <a href="https://github.com/danielgtaylor/aglio" class="aglio">aglio</a> on 16 May 2017</p><script>/* eslint-env browser */ | |
/* eslint quotes: [2, "single"] */ | |
'use strict'; | |
/* | |
Determine if a string ends with another string. | |
*/ | |
function endsWith(str, suffix) { | |
return str.indexOf(suffix, str.length - suffix.length) !== -1; | |
} | |
/* | |
Get a list of direct child elements by class name. | |
*/ | |
function childrenByClass(element, name) { | |
var filtered = []; | |
for (var i = 0; i < element.children.length; i++) { | |
var child = element.children[i]; | |
var classNames = child.className.split(' '); | |
if (classNames.indexOf(name) !== -1) { | |
filtered.push(child); | |
} | |
} | |
return filtered; | |
} | |
/* | |
Get an array [width, height] of the window. | |
*/ | |
function getWindowDimensions() { | |
var w = window, | |
d = document, | |
e = d.documentElement, | |
g = d.body, | |
x = w.innerWidth || e.clientWidth || g.clientWidth, | |
y = w.innerHeight || e.clientHeight || g.clientHeight; | |
return [x, y]; | |
} | |
/* | |
Collapse or show a request/response example. | |
*/ | |
function toggleCollapseButton(event) { | |
var button = event.target.parentNode; | |
var content = button.parentNode.nextSibling; | |
var inner = content.children[0]; | |
if (button.className.indexOf('collapse-button') === -1) { | |
// Clicked without hitting the right element? | |
return; | |
} | |
if (content.style.maxHeight && content.style.maxHeight !== '0px') { | |
// Currently showing, so let's hide it | |
button.className = 'collapse-button'; | |
content.style.maxHeight = '0px'; | |
} else { | |
// Currently hidden, so let's show it | |
button.className = 'collapse-button show'; | |
content.style.maxHeight = inner.offsetHeight + 12 + 'px'; | |
} | |
} | |
function toggleTabButton(event) { | |
var i, index; | |
var button = event.target; | |
// Get index of the current button. | |
var buttons = childrenByClass(button.parentNode, 'tab-button'); | |
for (i = 0; i < buttons.length; i++) { | |
if (buttons[i] === button) { | |
index = i; | |
button.className = 'tab-button active'; | |
} else { | |
buttons[i].className = 'tab-button'; | |
} | |
} | |
// Hide other tabs and show this one. | |
var tabs = childrenByClass(button.parentNode.parentNode, 'tab'); | |
for (i = 0; i < tabs.length; i++) { | |
if (i === index) { | |
tabs[i].style.display = 'block'; | |
} else { | |
tabs[i].style.display = 'none'; | |
} | |
} | |
} | |
/* | |
Collapse or show a navigation menu. It will not be hidden unless it | |
is currently selected or `force` has been passed. | |
*/ | |
function toggleCollapseNav(event, force) { | |
var heading = event.target.parentNode; | |
var content = heading.nextSibling; | |
var inner = content.children[0]; | |
if (heading.className.indexOf('heading') === -1) { | |
// Clicked without hitting the right element? | |
return; | |
} | |
if (content.style.maxHeight && content.style.maxHeight !== '0px') { | |
// Currently showing, so let's hide it, but only if this nav item | |
// is already selected. This prevents newly selected items from | |
// collapsing in an annoying fashion. | |
if (force || window.location.hash && endsWith(event.target.href, window.location.hash)) { | |
content.style.maxHeight = '0px'; | |
} | |
} else { | |
// Currently hidden, so let's show it | |
content.style.maxHeight = inner.offsetHeight + 12 + 'px'; | |
} | |
} | |
/* | |
Refresh the page after a live update from the server. This only | |
works in live preview mode (using the `--server` parameter). | |
*/ | |
function refresh(body) { | |
document.querySelector('body').className = 'preload'; | |
document.body.innerHTML = body; | |
// Re-initialize the page | |
init(); | |
autoCollapse(); | |
document.querySelector('body').className = ''; | |
} | |
/* | |
Determine which navigation items should be auto-collapsed to show as many | |
as possible on the screen, based on the current window height. This also | |
collapses them. | |
*/ | |
function autoCollapse() { | |
var windowHeight = getWindowDimensions()[1]; | |
var itemsHeight = 64; /* Account for some padding */ | |
var itemsArray = Array.prototype.slice.call( | |
document.querySelectorAll('nav .resource-group .heading')); | |
// Get the total height of the navigation items | |
itemsArray.forEach(function (item) { | |
itemsHeight += item.parentNode.offsetHeight; | |
}); | |
// Should we auto-collapse any nav items? Try to find the smallest item | |
// that can be collapsed to show all items on the screen. If not possible, | |
// then collapse the largest item and do it again. First, sort the items | |
// by height from smallest to largest. | |
var sortedItems = itemsArray.sort(function (a, b) { | |
return a.parentNode.offsetHeight - b.parentNode.offsetHeight; | |
}); | |
while (sortedItems.length && itemsHeight > windowHeight) { | |
for (var i = 0; i < sortedItems.length; i++) { | |
// Will collapsing this item help? | |
var itemHeight = sortedItems[i].nextSibling.offsetHeight; | |
if ((itemsHeight - itemHeight <= windowHeight) || i === sortedItems.length - 1) { | |
// It will, so let's collapse it, remove its content height from | |
// our total and then remove it from our list of candidates | |
// that can be collapsed. | |
itemsHeight -= itemHeight; | |
toggleCollapseNav({target: sortedItems[i].children[0]}, true); | |
sortedItems.splice(i, 1); | |
break; | |
} | |
} | |
} | |
} | |
/* | |
Initialize the interactive functionality of the page. | |
*/ | |
function init() { | |
var i, j; | |
// Make collapse buttons clickable | |
var buttons = document.querySelectorAll('.collapse-button'); | |
for (i = 0; i < buttons.length; i++) { | |
buttons[i].onclick = toggleCollapseButton; | |
// Show by default? Then toggle now. | |
if (buttons[i].className.indexOf('show') !== -1) { | |
toggleCollapseButton({target: buttons[i].children[0]}); | |
} | |
} | |
var responseCodes = document.querySelectorAll('.example-names'); | |
for (i = 0; i < responseCodes.length; i++) { | |
var tabButtons = childrenByClass(responseCodes[i], 'tab-button'); | |
for (j = 0; j < tabButtons.length; j++) { | |
tabButtons[j].onclick = toggleTabButton; | |
// Show by default? | |
if (j === 0) { | |
toggleTabButton({target: tabButtons[j]}); | |
} | |
} | |
} | |
// Make nav items clickable to collapse/expand their content. | |
var navItems = document.querySelectorAll('nav .resource-group .heading'); | |
for (i = 0; i < navItems.length; i++) { | |
navItems[i].onclick = toggleCollapseNav; | |
// Show all by default | |
toggleCollapseNav({target: navItems[i].children[0]}); | |
} | |
} | |
// Initial call to set up buttons | |
init(); | |
window.onload = function () { | |
autoCollapse(); | |
// Remove the `preload` class to enable animations | |
document.querySelector('body').className = ''; | |
}; | |
</script></body></html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment