WIXLIB

OpenAPI developmentwith PythonEuroPython2017@Rimini, 11 July 2017Takuro Wada

HiTa k u r o Wad aKabuku Inc.Software Engineer-Speaker of EuroPython 2016, PyConJP 2015Member of swagger codegen technical committee- Python, TypeScript@taxpontaxponhttp://takuro.ws2

Agenda1. What is OpenAPI?Introduction and basics2. OpenAPI toolsIntroduce some tools to increase your productivity3. Actual case studyIntroduce our company’s project3

What is OpenAPI?

What is OpenAPI?OpenAPI is API description language which is focusingon creating, evolving and promoting vendor neutraldescription format(Partially cited from https://www.openapis.org/about)You can write your API spec with OpenAPI5

What is OpenAPI?‣ Supported spec format- YAML and JSON‣ Based on JSON schema- Vocabulary to annotate andvalidate JSON‣ Originally known as SwaggerActual example spec in YAML format6

How to use OpenAPI?‣As API documents- Generate good looking documents- Share API spec in team-Frontend and Backend-Developers and non-developers- Public API Document for Any developers7

How to use OpenAPI?‣As API tools- Code generation-Codes for request data validation in server-Code for API calling in clients8

OpenAPI versions‣OpenAPI is originally known as Swagger- Swagger spec was renamed OpenAPI spec in 2016VersionRelease Date1.214 Mar 20142.08 Sep 20143.0Will be released in July repo9

OpenAPI’s competitors‣RESTful API DL (Description Language)- RAML (RESTful API Modeling Language)-YAML base- API Blueprint-Markdown base-Oracle acquired Apiary in Jan 201710

Google Trends!!toHSoOpenAPI (Swagger) is gathering more attention than others!

OpenAPI tools

OpenAPI tools‣Core tools- Developed by OpenAPI (Swagger) team‣Community tools- Developed by Community- Introduce Python tools in this session13

Core tools‣Swagger UI‣Swagger Editor‣Swagger Codegen14

Core tools (1/3)‣Swagger UI- Show spec with beautiful format- Directly API calling from browser- ger-api/swagger-ui15

Core tools (2/3)‣Swagger Editor- WYSIWYG Spec editor in web browser- Syntax highlighting, Autocompletion, Real time spec validation- ger-api/swagger-editor16

Core tools (3/3)‣Swagger Codegen- Generate server’s and client’s code from specSwaggerCodegenSwaggerSpecInputGenerateMultiple languages17

Community tools‣ There are many Python toolsfor OpenAPI-Validator-Code generator-Spec parser-Some tools are for the tegrations/#python-1918

bravado-core‣ Python library that adds client-side and server-side support forOpenAPI (2.7, 3.4 , developed by Yelp,https://github.com/Yelp/bravado-core)‣ Not dedicated to any specific framework (You can use it in you ownproject today)‣ Very simple to use‣ Features-ValidationMarshaling and Unmarshaling-Custom formats for type conversion19

bravado-core‣Spec exampleBook:type: objectrequired: [id]properties:id:type: integertitle:type: stringauthor:type: string20

bravado-core: (1)Validate‣Validation executionimport yamlfrom bravado core.spec import Spec# 1with open('openapi.yaml', 'r') as f:raw spec yaml.load(f)# 2spec Spec.from dict(raw spec)# 3book raw spec[‘definitions']['Book']# 4validate schema object(spec, book, target)1. Load YAML file with OpenAPIspec (JSON is also OK)2. Create Spec object3. Retrieve “Book” definition4. Validate (target is dict objectwhich is dumped from client’srequest)21

bravado-core: (1)Validate‣ if required property “id” is not defined in dict:validate schema object(spec, book, {})Codejsonschema.exceptions.ValidationError: 'id' is a required propertyResultFailed validating 'required' in schema:{'properties': {'author': {'type': 'string'},'id': {'type': 'integer'},'release date': {'format': 'date', 'type': 'string'},'title': {'type': 'string'}},'required': ['id'],'type': 'object','x-model': 'Book'}On instance:{}22

bravado-core: (1)Validation‣ If a property has invalid type value:validate schema object(spec, book, {"id": 1, "title": : 1 is not of type 'string'Failed validating 'type' in schema['properties']['title']:{'type': 'string'}On instance['title']:123

bravado-core: (2)Unmarshal‣Unmarshal (dict to object)from bravado core.unmarshal import unmarshal schema objectbook obj unmarshal schema object(spec, book,{"id": 1,"title": "Merchant of Venice”,“author": "William Shakespeare"})print(book obj)]CodeDict need to be convertedResultBook(author 'William Shakespeare', id 1, title 'Merchant of Venice')Model object is created !!24

bravado-core: (2)Unmarshal‣ Formatting in UnmarshalBook:type: objectrequired: [id]properties:id:type: integertitle:type: stringauthor:type: stringrelease date:type: stringformat: date]This property is added andexpected to be string with “date" format25

bravado-core: (2)Unmarshal‣ Formatting in UnmarshalCodebook obj unmarshal schema object(spec, book,{"id": 1,"title": "Merchant of Venice”,“author": "William Shakespeare”,“release date”: “2017-07-11”})print(book obj)]Dict need to be convertedBook(author 'William Shakespeare', id 1,release date datetime.date(2017, 7, 11), title 'Merchant of Venice')String with date format is successfully converted to a date object!!Result26

bravado-core: (2)Unmarshal‣Defined formatter- Default defined formatter:- byte, date, double, date-time, float, int32, int64- blob/master/bravado core/formatter.py)- Custom formatter by /master/docs/source/formats.rst27

bravado-core: (3)Marshal‣Marshal (object to dict)CodeBook spec.definitions['Book']book obj Book(id 1, title "Merchant of Venice",author "William Shakespeare”,“Book” objectrelease date date(2017, 7, 11))book dict marshal schema object(spec, book, book obj)print(book dict)]Result{'release date': '2017-07-11', 'title': 'Merchant of Venice', 'id': 1,'author': 'William Shakespeare'}Date object is successfully converted to string with date format!!28

bravado-core‣And many useful features- est/- ample29

Actual case study

Project overview‣Kabuku Connect- Manufacturing cloud platform- Connect people who want to make something andthe factories selected by AI31

Architecture‣Kabuku Connect‣Other services-Frontend: Angular (TypeScript)- Manufacturing-Backend: Python- Data analyzing servicemanagement serviceKabuku herServiceOtherService32

How OpenAPI is used‣ In Kabuku ConnectKabuku )Code generationfor API calling(1)GenerateAPI Document(3)Validation of requestparameters from clientSwagger codegenSwagger UIbravado-coreOtherServiceOtherService33

How OpenAPI is used‣ With other servicesKabuku )Code generationfor API calling(1)GenerateAPI DocumentSwagger codegenSwagger UIOtherServiceOtherService34

Implementation workflow1. Design‣ API structure and write OpenAPI spec2. Implementation‣ Frontend (Angular, Typescript)-Using generated clients code and mock server‣ Backend (Python)‣ Frontend and Backend can be implemented in parallel35

Impression‣Using OpenAPI tools decrease yourtasks so much- Document generation- Code generation-er yVFrontend and Backend, API provider and API!evitducorPconsumer can be implemented in parallel36

Recap

Recap‣OpenAPI is a hot technology to describeAPI specification‣There are many tools to increase yourproductivity with OpenAPI!!toHSo‣You learned actual case with OpenAPI38

Required more contributors!‣New Open API Spec (Version 3.0) will bereleased in July 2017- There are many added good features- Tools need to support OAS v3L e t ’s!etubiCon t r39

We are hiring!‣ Python‣ C DeveloperDeveloper‣ FrontendDeveloper‣ Angular/Three.js‣ Youcan use 3D printers all you want‣ International‣3membersGoogle Developer Expertshttps://www.kabuku.co.jp/enSome 3D printed members40

OpenAPI development with Python EuroPython2017@Rimini, 11 July 2017 Takuro Wada. Hi 2 Kabuku Inc. . -Frontend: Angular (TypeScript) -Backend: Python Backend . 2. Implementation ‣ Frontend (Angular, Typescript) -Using generated clients code and mock server