Movatterモバイル変換

[0]ホーム
URL:

developersIOproduced by Classmethod
[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成

[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成

2015.02.18

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

APIを作るとき

みなさん、毎日API使ってますか？私は、ワンライナーでAPIをコールすることにハマっています。さて、いつも使っているAPIを作る側になったとき、どのように設計していますでしょうか？また、作ったAPIをどのように使ってもらっていますか？そんな疑問に応えるサービスがApiaryです。

Apiaryとは？

Apiaryは、REST APIをサクッと書けるサービスです。また、APIドキュメントも生成してくれます。モックサーバも提供してくれます。API利用サンプルコードも作ってくれます。うん、使わないって選択肢は無いですねｗ。

無料登録すると早速使えるようになります。チームでプライベートなAPI開発をしたければ有料プランを選択してください。

screenshot 2015-02-18 10.00.41

API開発の流れ

API開発の流れは、まずはじめにMarkdown形式でドキュメントを書きます。既にサンプルがあるのでこれを使ってみましょう。

screenshot 2015-02-18 10.02.22

右側にドキュメントのプレビューが現れましたね。さっそく使ってみましょう。List all Notesを選択します。すると、APIのモックを利用できる画面が出てきます。

screenshot 2015-02-18 11.37.35

ドキュメントを書いただけなのにAPIを実行できました！

screenshot 2015-02-18 11.38.37

CORS設定

API利用時にCORS（クロスドメインアクセス）をしたいときがありますよね。Apiaryの設定画面でON/OFF可能です。

サンプルコードの利用

できあがったモックAPIサーバを利用するサンプルコードも自動生成されます。これはありがたいですね！

cURL

curl --include \'http://private-ee96-satoshi7.apiary-mock.com/notes'

Java

import javax.ws.rs.client.Client;import javax.ws.rs.client.ClientBuilder;import javax.ws.rs.client.Entity;import javax.ws.rs.core.Response;import javax.ws.rs.core.MediaType;Client client = ClientBuilder.newClient();Response response = client.target("http://private-ee96-satoshi7.apiary-mock.com")  .path("/notes")  .request(MediaType.TEXT_PLAIN_TYPE)  .get();System.out.println("status: " + response.getStatus());System.out.println("headers: " + response.getHeaders());System.out.println("body:" + response.readEntity(String.class));

JavaScript

var Request = new XMLHttpRequest();Request.open('GET', 'http://private-ee96-satoshi7.apiary-mock.com/notes');Request.onreadystatechange = function () {  if (this.readyState === 4) {    console.log('Status:', this.status);    console.log('Headers:', this.getAllResponseHeaders());    console.log('Body:', this.responseText);  }};Request.send(JSON.stringify(body));

Node.js

var request = require('request');request('http://private-ee96-satoshi7.apiary-mock.com/notes', function (error, response, body) {  console.log('Status:', response.statusCode);  console.log('Headers:', JSON.stringify(response.headers));  console.log('Response:', body);});

Perl

require LWP::UserAgent;my $ua   = LWP::UserAgent->new;my $response = $ua->get("http://private-ee96-satoshi7.apiary-mock.com/notes");print $response->as_string;

Python

from urllib2 import Request, urlopenrequest = Request('http://private-ee96-satoshi7.apiary-mock.com/notes')response_body = urlopen(request).read()print response_body

PHP

<?php$ch = curl_init();curl_setopt($ch, CURLOPT_URL, "http://private-ee96-satoshi7.apiary-mock.com/notes");curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);curl_setopt($ch, CURLOPT_HEADER, FALSE);$response = curl_exec($ch);curl_close($ch);var_dump($response);[/code]<h4>Ruby</h4><h4>Go</h4>package mainimport ("fmt""io/ioutil""net/http")func main() {client := &http.Client{}req, _ := http.NewRequest("GET", "http://private-ee96-satoshi7.apiary-mock.com/notes", nil)resp, err := client.Do(req)if err != nil {fmt.Println("Errored when sending request to the server")return}defer resp.Body.Close()resp_body, _ := ioutil.ReadAll(resp.Body)fmt.Println(resp.Status)fmt.Println(string(resp_body))}

C#

using System;using System.Net.Http;var baseAddress = new Uri("http://private-ee96-satoshi7.apiary-mock.com/");using (var httpClient = new HttpClient{ BaseAddress = baseAddress }){  using(var response = await httpClient.GetAsync("notes"))  {         string responseData = await response.Content.ReadAsStringAsync();  }}

VisualBasic

Dim request = TryCast(System.Net.WebRequest.Create("http://private-ee96-satoshi7.apiary-mock.com/notes"), System.Net.HttpWebRequest)request.Method = "GET"request.ContentLength = 0Dim responseContent As StringUsing response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)  Using reader = New System.IO.StreamReader(response.GetResponseStream())    responseContent = reader.ReadToEnd()  End UsingEnd Using

Groovy

import groovyx.net.http.RESTClientimport static groovyx.net.http.ContentType.JSONimport groovy.json.JsonSlurperimport groovy.json.JsonOutput@Grab (group = 'org.codehaus.groovy.modules.http-builder', module = 'http-builder', version = '0.5.0')def client = new RESTClient("http://private-ee96-satoshi7.apiary-mock.com")response = client.get( path : "/notes")println("Status:" + response.status)if (response.data) {  println("Content Type: " + response.contentType)  println("Body:\n" + JsonOutput.prettyPrint(JsonOutput.toJson(response.data)))}

Objective-C

NSURL *URL = [NSURL URLWithString:@"http://private-ee96-satoshi7.apiary-mock.com/notes"];NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:URL];[request setHTTPMethod:@"GET"];NSURLSession *session = [NSURLSession sharedSession];NSURLSessionDataTask *task = [session dataTaskWithRequest:request                                        completionHandler:                              ^(NSData *data, NSURLResponse *response, NSError *error) {                                  if (error) {                                      // Handle error...                                      return;                                  }                                  if ([response isKindOfClass:[NSHTTPURLResponse class]]) {                                      NSLog(@"Response HTTP Status code: %ld\n", (long)[(NSHTTPURLResponse *)response statusCode]);                                      NSLog(@"Response HTTP Headers:\n%@\n", [(NSHTTPURLResponse *)response allHeaderFields]);                                  }                                  NSString* body = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];                                  NSLog(@"Response Body:\n%@\n", body);                              }];[task resume];

Swift

let url = NSURL(string: "http://private-ee96-satoshi7.apiary-mock.com/notes")!let request = NSMutableURLRequest(URL: url)let session = NSURLSession.sharedSession()let task = session.dataTaskWithRequest(request) { (data: NSData!, response: NSURLResponse!, error: NSError!) in    if error != nil {        // Handle error...        return    }    println(error)    println(response)    println(NSString(data: data, encoding: NSUTF8StringEncoding))}

Swift Representor

import Alamofireimport Representorlet blueprint = Blueprint(named: "blueprint.json", bundle: nil)let baseURL = NSURL(string: "http://private-ee96-satoshi7.apiary-mock.com/")if let transition = blueprint?.transition("Notes Collection", action: "List all Notes") {  request(baseURL, transition, parameters:parameters)    .response { (request, response, data, error) in      // Handle the response    }}

まとめ

Markdownを書いたらAPIとドキュメントが出来上がっていますので、クライアントサイドとサーバーサイドで後からごにょごにょ繋げるのではなく、先にAPI（アプリケーションをプログラミングするときに使うインタフェース）部分を決めることで、開発は大分楽になるのではないでしょうか。

参照情報

Apiary

この記事をシェアする

FacebookHatena blogX

EVENTS

セミナー一覧会社説明会一覧勉強会一覧
[8]ページ先頭
©2009-2025 Movatter.jp