Share
Embed
Transcript
76 slides
-
໘ͳཁҼ • ༷ॻͷϑΥʔϚοτ͕ఆ·͍ͬͯͳ͍ɻ • JSON Schemaʁ Swaggerʁ • ࣅͨΑ͏ͳ͜ͱΛ܁Γฦ͠ॻ͘͜ͱଟ͍ •
։ൃ༻ͷϞοΫ͍Δ • υΩϡϝϯτͱݱঢ়ͱͷ߹ੑ(maintenance) • υΩϡϝϯτ͋Δ͕ɺ·࣮ͩࡍʹಈ͘ͷ͕࣮͞Ε͍ͯͳ͍ -
API Blueprint • MarkdownͰهड़͞ΕͨWeb API(ಛʹRESTful ͳAPI)ͷ༷Λղऍͯ͘͠ΕΔ • ਓ͕ಡΈ͍͢ʂ • ԿΛ࡞ΕΔ͔
• υΩϡϝϯτ(aglio) • ϞοΫαʔόʔ(api-mock) • ςετ࣮ߦ(dredd) • ·ͱΊͯੜͰ͖Δ͔ΒapibϑΝΠϧΛཧ͢Δ͚ͩͰࡁΉ -
ࠓͷ͓͠ͳ͕͖ • apiblueprintΛମݧʂ • Hello world! • γϯϓϧͳRestAPIΛհͯ࣍͠ͷ3ͭΛͬͯΈΔ • υΩϡϝϯτ
• ϞοΫαʔόʔ • ؆୯ͳςετ • rails gͰapibϑΝΠϧΛੜ͢ΔGemͷհ -
Install Battle λʔϛφϧͰҎԼΛೖྗ $ gem install rails dredd_hooks $ brew
install node npm $ npm install -g aglio api-mock dredd • API Blueprint༷ॻͳͷͰॲཧܥผ • ࠓճNode.jsΛ࣮ͬͯ͞Εͨaglioͱapi-mockͱdreddΛར༻ • aglio υΩϡϝϯτੜ • api-mock ϞοΫαʔόʔੜ • dredd ςετ࣮ߦ -
Editor Package • Sublimetext • API Blueprint https://github.com/apiaryio/api-blueprint-sublime-plugin • Atom
• language-api-blueprint https://github.com/danielgtaylor/atom-language-api-blueprint • Vim • apiblueprint.vim https://github.com/kylef/apiblueprint.vim -
Hello world! • ͜Ε/messageʹGETϝιουΛ࣮ߦ͢Δͱ Content-Type͕text/plainͷ"Hello, World!"͕ฦΔ $ cat << 'EOF'
> helloworld.apib # GET /message + Response 200 (text/plain; charset=utf-8) Hello, World! EOF -
υΩϡϝϯτੜ • 2௨Γͷख๏ • HTMLʹม $ aglio -i helloworld.apib -o
helloworld.html • Preview serverΛཱͯΔ • apibϑΝΠϧΛsave͢Δͨͼʹੜ͠ͳ͓ͯ͘͠ΕΔ • save࣌ʹจ๏ΤϥʔνΣοΫͯ͘͠ΕΔ $ aglio -i helloworld.apib -s -
ϞοΫΞοϓαʔόʔΛཱͯΔ • api-mockίϚϯυʹ.apibϑΝΠϧΛ͢ $ api-mock helloworld.apib • ͜ΕͰlocalhost:3000ʹϞοΫαʔόʔ͕ىಈ •
ΞΫηεͯ͠ΈΔͱςΩετσʔλͰhello world!ͱग़ྗ͞ΕΔ • (http://localhost:3000/message) -
Restful API GET /message • HTTPϝιουϦιʔεΛͲ͏ૢ࡞͍͔ͨ͠Λද͢ • ϦιʔεɿWeb্ʹଘࡏ͢Δʮใʯ •
URLϦιʔεͷ໊લ • APIͷॲཧͷ݁ՌɺεςʔλεɾίʔυͰද͢ • ͜ͷ߹/messageʹGETͱ͍͏ૢ࡞Λ͍ͨ͠ -
user API • ࠓճRuby on RailsΛ༻͍ͯɺγϯϓϧͳRestfulAPIΛ࡞͢Δ • ·ͣRailsͰҎԼΛ࣮ߦ $ rails
new apib-sample --api -T $ cd apib-sample $ rails g scaffold User name age:integer admin:boolean $ rake db:migrate • --apiAPIϞʔυ (apiʹؔ͠ͳ͍ϑΝΠϧΛੜ͠ͳ͍) • -T--skip-test-unit (TestUnitΛΈࠐ·ͳ͍) • rails g scaffold • σʔλϕʔεͷςʔϒϧͷొ(CREATE)ɺࢀর(READ)ɺߋ৽(UPDATE)ɺআ ʢDELETEʣͱ͍͏CRUDΛߦ͏WebΞϓϦέʔγϣϯͷͻͳܕͱͳΔίʔυΛࣗಈੜɻ -
user API VTFS"1*ͷॲཧ༰ ରͱͳΔϦιʔε ࣮ߦΞΫγϣϯ VTFSΛՃ͢Δ VTFSશମ 1045VTFST VTFSΛશͯऔಘ͢Δ
VTFSશମ (&5VTFST *EͱҰக͢ΔVTFSΛऔಘ͢Δ *EͱҰக͢ΔVTFS (&5VTFST\JE^ *EͱҰக͢ΔVTFSΛߋ৽͢Δ *EͱҰக͢ΔVTFS 165VTFST\JE^ *EͱҰக͢ΔVTFSΛআ͢Δ *EͱҰக͢ΔVTFS %&-&5&VTFST\JE^ -
user API VTFS"1*ͷॲཧ༰ ॲཧͷ݁ՌฦΔ)551Ϩεϙϯε εςʔλείʔυ #PEZ VTFSΛՃ͢Δ Ճͨ͠σʔλ
VTFSΛશͯऔಘ͢Δ ରσʔλ *EͱҰக͢ΔVTFSΛऔಘ͢Δ ରσʔλ *EͱҰக͢ΔVTFSΛߋ৽͢Δ ߋ৽ͨ͠σʔλ *EͱҰக͢ΔVTFSΛআ͢Δ ۭ -
user API • దʹuserΛՃ͢Δ $ rails console irb(main):001:0> User.create(name: "Go
Takagi", age: 22, admin: true) irb(main):002:0> User.create(name: "Dean Fujioka", age: 35, admin: false) irb(main):003:0> User.create(name: "Kasumi Arimura", age: 23, admin: false) -
user API • RailsΛ্ཱͪ͛ͯΞΫηεͯ͠ΈΔ $ rails server => Booting Puma
=> Rails 5.0.0.rc1 application starting in development on http://localhost:3000 => Run `rails server -h` for more startup options • jsonϑΝΠϧ͕ฦ͖ͬͯͨʂ -
user.apib FORMAT: 1A HOST: http://localhost:3000 # user API Welcome
to the user API. # users action [/users] ## Create user [POST] ## Get users [GET] # user action [/users/{id}] ## Get user [GET] ## Update user [PUT] ## Delete user [DELETE] # Data Structures ## users (object) -
Metadata section • API BlueprintυΩϡϝϯτͷઌ಄σʔλ͕ϝλσʔλ ηΫγϣϯͱͳ͍ͬͯΔ • কདྷతͳ֦ுͳͲʹඋ͑ͯόʔδϣϯใΛهࡌͰ͖Δ • ݱࡏ1A
• ఏڙ͢Δαʔόʔͷϗετهड़Մೳ FORMAT: 1A HOST: http://localhost:3000 # user API Welcome to the user API. # users action [/users] ## Create user [POST] ## Get users [GET] # user action [/users/{id}] ## Get user [GET] ## Update user [PUT] ## Delete user [DELETE] # Data Structures ## users (object) -
API name & overview section • # user API ͕APIͷ໊শ
• ԼʹAPIશମͷઆ໌͕ॻ͚Δ FORMAT: 1A HOST: http://localhost:3000 # user API Welcome to the user API. # users action [/users] ## Create user [POST] ## Get users [GET] # user action [/users/{id}] ## Get user [GET] ## Update user [PUT] ## Delete user [DELETE] # Data Structures ## users (object) -
Resource sections • ઃܭॻͷϝΠϯ • ۩ମతͳશମ૾ӈͷΑ͏ʹͳΔ • Ϧιʔε͝ͱʹݟग़͠ͰάϧʔϓΛ͘͘Γɺ HTTPϝιουΛҰͭԼͷϨϕϧͰॻ͘
FORMAT: 1A HOST: http://localhost:3000 # user API Welcome to the user API. # users action [/users] ## Create user [POST] ## Get users [GET] # user action [/users/{id}] ## Get user [GET] ## Update user [PUT] ## Delete user [DELETE] # Data Structures ## users (object) -
(࠶ܝ)user API VTFS"1*ͷॲཧ༰ ରͱͳΔϦιʔε ࣮ߦΞΫγϣϯ VTFSΛՃ͢Δ VTFSશମ 1045VTFST VTFSΛશͯऔಘ͢Δ
VTFSશମ (&5VTFST *EͱҰக͢ΔVTFSΛऔಘ͢Δ *EͱҰக͢ΔVTFS (&5VTFST\JE^ *EͱҰக͢ΔVTFSΛߋ৽͢Δ *EͱҰக͢ΔVTFS 165VTFST\JE^ *EͱҰக͢ΔVTFSΛআ͢Δ *EͱҰக͢ΔVTFS %&-&5&VTFST\JE^ -
(࠶ܝ)user API VTFS"1*ͷॲཧ༰ ॲཧͷ݁ՌฦΔ)551Ϩεϙϯε εςʔλείʔυ #PEZ VTFSΛՃ͢Δ Ճͨ͠σʔλ
VTFSΛશͯऔಘ͢Δ ରσʔλ *EͱҰக͢ΔVTFSΛऔಘ͢Δ ରσʔλ *EͱҰக͢ΔVTFSΛߋ৽͢Δ ߋ৽ͨ͠σʔλ *EͱҰக͢ΔVTFSΛআ͢Δ ۭ -
Get users [GET /users] ## Get users [GET] Returns
user list. + Response 200 (application/json; charset=utf-8) + Attributes (array) + Attributes (object) + id: 1 (number) - Id + name: NAME (string) + age: 1 (number) + admin: false (boolean) + created_at: `2000-01-01 00:00:00` (string) - CreatedTime + updated_at: `2000-01-01 00:00:00` (string) - UpdatedTime • #ͷޙʹ໊শɺԼʹઆ໌Λॻ͚Δ • action”+”Λ༻͍ͯListͰॻ͍͍ͯ͘ • ࠓճྻΛฦ͢Response 200 -
Header • ੜ͞ΕͨυΩϡϝϯτͰHeaderʹapplication/json; charset=utf-8͕ࢦఆ͞Ε͍ͯΔ • ΑΓઃఆ͕ඞཁͳΒ+Attributesͱಉ͡֊ʹ+HeadersͰهࡌ + Response 200
(application/json; charset=utf-8) + Headers Connection: keep-alive Content-Type: multipart/form-data, boundary=AaB03x + Attributes (array) + Attributes (object) -
Create user [POST /users] ## Create user [POST] Create
a new user + Request users (application/json; charset=utf-8) + Attributes + name: NAME (string) + age: 1 (number) + admin: false (boolean) + Response 201 (application/json; charset=utf-8) + Attributes + id: 1 (number) - Id + name: NAME (string) + age: 1 (number) + admin: false (boolean) + created_at: `2000-01-01 00:00:00` (string) - CreatedTime + updated_at: `2000-01-01 00:00:00` (string) - UpdatedTime -
Data Structures • ಉ͡σʔλΛԿ͏ͷ໘ͩ͠ͳΜ͔಄ѱ͍ • Data Structuresʹఆ͓͚ٛͯ͠ݺͼग़͢͜ͱ͕Մೳ # Data
Structures ## users (object) + id: 1 (number) - Id + name: NAME (string) + age: 1 (number) + admin: false (boolean) + created_at: `2000-01-01 00:00:00` (string) - CreatedTime + updated_at: `2000-01-01 00:00:00` (string) - UpdatedTime FORMAT: 1A HOST: http://localhost:3000 # user API Welcome to the user API. # users action [/users] ## Create user [POST] ## Get users [GET] # user action [/users/{id}] ## Get user [GET] ## Update user [PUT] ## Delete user [DELETE] # Data Structures ## users (object) -
Data Structures • ͢Δͱ͜ͷΑ͏ʹݺΔɻ͖ͬ͢Γ ## Create user [POST] Create
a new user + Request users (application/json; charset=utf-8) + ……… + Response 201 (application/json; charset=utf-8) + Attributes (users) ## Get users [GET] Returns user list. + Response 200 (application/json; charset=utf-8) + Attributes (array) + (users) -
Parameter /users{id} # user action [/users/{id}] + Parameters +
id: `1` (enum[string]) - The ID of the desired user. + Members + `1` + `2` + `3` ## Get user [GET] • parameter͕͋Δ߹ॳΊʹ+parameterΛఆٛ͢Δͱ Ҏ߱ͷϦΫΤετશͯͰར༻ग़དྷΔ • ࠓճMembersΛड͚ೖΕΔ༷ʹ͕ͨ͠ଞʹॳظ requiredઃఆͰ͖Δ -
Get user [POST /users{id}] # user action [/users/{id}] +
Parameters + id: `1` (enum[string]) - The ID of the desired user. + Members + `1` + `2` + `3` ## Get user [GET] Returns user. + Response 200 (application/json; charset=utf-8) + Attributes (users) -
Update user [PUT /users{id}] ## Update user [PUT] update
user. + Request users (application/json; charset=utf-8) + Attributes + name: NAME (string) + age: 1 (number) + admin: false (boolean) + Response 200 (application/json; charset=utf-8) + Attributes (users) • ߋ৽σʔλΛRequest • (idͷσʔλΛ্ॻ͖ͯ͠)Response 200 -
Delete user [DELETE /users{id}] ## Delete user [DELETE] Delete
user. + Response 204 • (idͷσʔλΛআͯ͠) Response 204 -
dredd_hooks • ςετ࣮ߦ࣌ͷલޙʹҰఆͷಈ࡞ΛڬΊΔ (before or after) • ࠓճͷ߹parameterͷΛ1͔ΒPOSTͯ͠ੜ͞ Εͨσʔλͷidʹ্ॻ͖ͯ͠ಈ࡞͍ͤͨ͞ɻ •
ࢦఆͷํʮϦιʔεάϧʔϓ໊ > ϦΫΤετ໊ʯ -
POSTσʔλͷҰ࣌อଘ • apibϑΥϧμʹdredd_hooks.rbϑΝΠϧΛ࡞ • transaction͔ΒPOSTͷσʔλΛୀආ require 'json' include DreddHooks::Methods
response_stash = {} after "users action > Create user" do |transaction| # saving HTTP response to the stash response_stash[transaction['name']] = transaction['real'] end -
idͷऔಘ • response_stash͔ΒidΛऔಘ͢Δؔͷఆٛ def get_input(transaction, response_stash) #reusing data from
previous response here parsed_body = JSON.parse response_stash['users action > Create user'] ['body'] machine_id = parsed_body['id'] #replacing id in URL with stashed id from previous response transaction['fullPath'].gsub! '1', machine_id.to_s end -
hooksͷઃఆ • parameterΛ༻͍ΔΞΫγϣϯͷલʹઌʹఆٛ ͨؔ͠Λݺͼग़͢ before "user action > Get
user" do |transaction| get_input(transaction, response_stash) end before "user action > Update user" do |transaction| get_input(transaction, response_stash) end before "user action > Delete user" do |transaction| get_input(transaction, response_stash) end -
require 'json' include DreddHooks::Methods response_stash = {} def get_input(transaction,
response_stash) #reusing data from previous response here parsed_body = JSON.parse response_stash['users action > Create user']['body'] machine_id = parsed_body['id'] #replacing id in URL with stashed id from previous response transaction['fullPath'].gsub! '1', machine_id.to_s end after "users action > Create user" do |transaction| # saving HTTP response to the stash response_stash[transaction['name']] = transaction['real'] end before "user action > Get user" do |transaction| get_input(transaction, response_stash) end before "user action > Update user" do |transaction| get_input(transaction, response_stash) end before "user action > Delete user" do |transaction| get_input(transaction, response_stash) end -
configϑΝΠϧͷੜ • λʔϛφϧͰapibϑΥϧμ্Ͱdredd initΛ࣮ߦ͠ɺ ԼઢͷΑ͏ʹઃఆ • ΓEnter $ dredd
init ? Location of the API blueprint (apiary.apib) user.apib ? Command to start API backend server e.g. (bundle exec rails server) rails server -b 0.0.0.0 ? URL of tested API endpoint http://localhost:3000 ? Programming language of hooks ruby ? Do you want to use Apiary test inspector? (Y/n) -
࣮ߦ • ੜ͞Εͨdredd.ymlͷҎԼͷͱ͜ΖΛEdit $ dredd complete: 5 passing, 0
failing, 0 errors, 0 skipped, 5 total complete: Tests took 2173ms complete: See results in Apiary at: https://app.apiary.io/public/ tests/run/f961c845-e6c6-4020-9d06-5c5545841b16 info: Sending SIGTERM to the backend server - Gracefully stopping, waiting for requests to finish === puma shutdown: 2016-05-10 21:04:36 +0900 === - Goodbye! Exiting -
apiblueprint-rails • ੜ͢Δͱ͖ʹscaffoldίϚϯυҰॹʹݺͼग़͢ • ΦϓγϣϯͰΓସ͑Մೳ • —apidoc-dirͰੜϑΥϧμΛมߋ • —generate-typeͰੜίϚϯυΛมߋ(none, model,
…) $ rails g apiblueprint Person name age:integer admin:boolean create doc/person.apib invoke active_record create db/migrate/20160511104619_create_people.rb create app/models/person.rb invoke resource_route route resources :people invoke scaffold_controller create app/controllers/people_controller.rb -
FORMAT: 1A # person API Write an overall API
discription. # people action [/people] Write a discription. ## Create person [POST] Write a [POST] discription. + Request people (application/json; charset=utf-8) + Attributes + name: MyString (string) + age: 1 (number) + admin: false (boolean) + Response 201 (application/json; charset=utf-8) + Attributes (people) ## Delete person [DELETE] Write a [DELETE] discription. + Response 204 # Data Structures ## people (object) + id: 1 (number) - Id + name: MyString (string) + age: 1 (number) + admin: false (boolean) + created_at: `2000-01-01 00:00:00` (string) - CreatedTime + updated_at: `2000-01-01 00:00:00` (string) - UpdatedTime -
·ͱΊ • apiblueprintͱͦͷपΓͷαʔϏεΛར༻ͨ͠ɻ • markdown͔ͩΒ͍͍ׅͪͪހ͕ͳͯ͘json-formatΑΓΔ͔ʹݟ͍͢ • ͜͜ͷαʔϏε͔ͩΒ·ͩ·ͩൃలੑʹظͰ͖Δɻ • ςετ·ΘΓʹظ •
ݸਓແྉ, ஂମ༗ྉͰapiaryαʔόʔ্ͰαʔϏεల։ • apibϑΝΠϧ͔ΒAPIར༻αϯϓϧίʔυͷੜ • githubͱͷ࿈ܞ