SlideShare a Scribd company logo
MetaCPAN,
Mojolicious
and
OpenAPI
- During meta::hack 3 work
with Joel Berger on
integrating/documenting
OpenAPI
with the MetaCPAN API via
Mojolicious.
Overview of how OpenAPI was
integrated into MetaCPAN with
Mojolicious.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The OpenAPI Specification originated as the
Swagger specification
- renamed to separate the API description format
(OpenAPI) from the open source
tooling (Swagger).
- used to provide documentation to an existing API, or
when creating a new one.
- For MetaCPAN API, we set out to provide
documentation to the existing API, but
through discussion, validation and driving the API
calls as well.
What is OpenAPI?
OpenAPI is a specification for designing, documenting,
validating and driving your RESTful API.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- Most importantly, the OpenAPI
spec becomes the one source of
truth for the API
- documentation
- routing
- validation
- responses
One
Source
of
Truth
- There are discovery tools that will
assist in writing the specification.
- We chose to write the definition by
hand (in vim of course) and use tools
to
generate the documentation and to
integrate the specification into
MetaCPAN.
The Tools
- Interactive map that shows
each layers options
- it includes acceptable values
and documentation
OpenAPI Map
The OpenAPI Map is an interactive site to aid in working with the OpenAPI Specification.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- ReDoc creates an interactive
page providing documentation
and examples based
on the details provided in the
OpenAPI specification file.
- this is what creates the
documentation for your API
ReDoc
ReDoc — OpenAPI/Swagger-generated API Reference Documentation
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
— OpenAPI / Swagger plugin for
Mojolicious
- Author: Jan Henning Thorsen
- Reads the OpenAPI specification file
and adds the appropriate routes and
validations for your Mojolicious
based application.
Mojolicious::Plugin::OpenAPI
Mojolicious::Plugin::OpenAPI — OpenAPI / Swagger plugin for Mojolicious
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- Author: Jan Henning Thorsen
- Integrated into the
Mojolicious::Plugin::OpenAPI module
- provides the input and output
validation
- providing validation for the
specification file itself.
JSON::Validator
JSON::Validator — Validate data against a JSON schema
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
Getting Started
- going to start with setting up
ReDoc as it is quite simple to
configure
ReDoc
ReDoc includes a HTML template to be served as a static file for customizing how the
documentation is displayed.
<!DOCTYPE html>
<html>
<head>
<title>MetaCPAN API</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url="./v1.yml" lazy-rendering="1" required-props-first="1" path-in-middle-panel="1"></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The import part here is the
redoc tag and the spec-
url
- the html and spec file must
be in a location that the server
will serve static files from
ReDoc
ReDoc includes a HTML template to be served as a static file for customizing how the
documentation is displayed.
<!DOCTYPE html>
<html>
<head>
<title>MetaCPAN API</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url="./v1.yml" lazy-rendering="1" required-props-first="1" path-in-middle-panel="1"></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- specification files can be quite long,
breaking it down for demonstration
purposes
- later I'll show how to organize better
- specification can be in either JSON or
YAML
- YAML supports multiline attribute values
making it much easier to read and
write with less formatting
The OpenAPI Specification File
The specification file is v1.yml
swagger: "2.0"
info:
version: "1.0.0"
title: "MetaCPAN API"
basePath: "/v1"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- Define the version of the
OpenAPI spec to use.
- Version 2.0 still uses
swagger as the key
The OpenAPI Specification File
The specification file is v1.yml
swagger: "2.0"
info:
version: "1.0.0"
title: "MetaCPAN API"
basePath: "/v1"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- General information about
the API
The OpenAPI Specification File
The specification file is v1.yml
swagger: "2.0"
info:
version: "1.0.0"
title: "MetaCPAN API"
basePath: "/v1"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- common path shared
throughout the API
The OpenAPI Specification File
The specification file is v1.yml
swagger: "2.0"
info:
version: "1.0.0"
title: "MetaCPAN API"
basePath: "/v1"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- configuration of API paths
are contained in sections
named after the URL path to
access them
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- the URL path to access this
portion of the API
- the basePath is
automatically prefixed to the
URL on consumption
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The HTTP methods that the
endpoint accepts
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- A unique identifier for the
method
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- an extension attribute used
by Mojolicious
- This attribute points to the
name of the class in the
application and the
method to call separated by #
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- A description of the API
Endpoint
Defining an Endpoint
Each of the paths available to the API are defined within the
paths object.
paths:
/search/web:
get:
operationId: search_web
x-mojo-to: Search#web
summary: Perform API search in the same fashion as the Web UI
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The parameters that the
HTTP method accepts
Defining Parameters
Each method can define its own parameters.
parameters:
- name: q
in: query
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.
See also `collapsed`
type: string
# Define the attribute as required
required: true
- name: from
in: query
description: The offset to use in the result set
type: integer
default: 0
- name: size
in: query
description: Number of results per page
type: integer
default: 20
- name: collapsed
in: query
description: |
Force a collapsed even when searching for a particular
distribution or module name.
type: boolean
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The parameter attribute
identifies the parameters and
accepts an array of objects.
Defining Parameters
Each method can define its own parameters.
parameters:
- name: q
in: query
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.
See also `collapsed`
type: string
# Define the attribute as required
required: true
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- In this instance the parameter name is q
- The location to parse the parameter from is from the
query
- parameters are accessible from within Mojolicious by
name (I'll show the calls later)
- in defines the location of the parameter:
- this instance is query
- header
- path
- formData
- body
Defining Parameters
Each method can define its own parameters.
parameters:
- name: q
in: query
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.
See also `collapsed`
type: string
required: true
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- Document what the parameter is.
- This example uses the YAML
HEREDOC syntax to make the
description easier to read and write.
- using the HEREDOC also allows
for paragraph separation in the
documentation
Defining Parameters
Each method can define its own parameters.
parameters:
- name: q
in: query
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.
See also `collapsed`
type: string
required: true
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The type of the value that the API accepts:
- array
- boolean
- integer
- number
- null
- object
- string
- required does what it says.
Defining Parameters
Each method can define its own parameters.
parameters:
- name: q
in: query
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.
See also `collapsed`
type: string
required: true
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- the responses attribute
contains objects keyed on the
HTTP response code or the
keyword default
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- response codes are defined
by HTTP status numbers
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The schema defines what
the result will look like
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The schema defines what
the result will look like
- objects
- primitives
- arrays
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- While items can be further
broken into properties per
item,
- type object is a catch all
Defining the Response
The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling.
responses:
200:
description: Search response
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
type: object
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- I'll admit, this is taken right from
the error definitions from the
OpenAPI repository
- https://github.com/OAI/
OpenAPI-Specification/blob/
master/examples/v2.0/yaml/
petstore.yaml#L92-L101
Error Definitions
Error messages can be defined by HTTP status codes or default.
default:
description: "unexpected error"
schema:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- Up until now all this work is
defining the API spec
- now to use it
Hooking
in
Mojolicious
- Additions to the Mojolicious
application consist of enabling
the plugin
Mojolicious Application
package MetaCPAN::API;
use Mojo::Base 'Mojolicious';
sub startup {
$self->plugin(
'OpenAPI' => { url => $self->home->rel_file('root/static/v1.yml') } );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- configures the API plugin
- url points to the OpenAPI
specification file
Mojolicious Application
package MetaCPAN::API;
use Mojo::Base 'Mojolicious';
sub startup {
$self->plugin(
'OpenAPI' => { url => $self->home->rel_file('root/static/v1.yml') } );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- this is an example of the
Search web interface from
MetaCPAN
- as you can see there's not a
lot of code to the method
Mojolicious Controller
Configure the controller to use the OpenAPI plugin to validate and extract parameters.
package MetaCPAN::API::Controller::Search;
use Mojo::Base 'Mojolicious::Controller';
sub web {
my $c = shift;
return unless $c->openapi->valid_input;
my $args = $c->validation->output;
my @search = ( @{$args}{qw/q from size/} );
push @search, $args->{collapsed} if exists $args->{collapsed};
my $results = $c->model->search->search_web(@search);
return $c->render( json => $results );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- validate the parameters
against the specification
- return undef triggers an
error, resulting in a message
specifying the
validation issue
Mojolicious Controller
Configure the controller to use the OpenAPI plugin to validate and extract parameters.
package MetaCPAN::API::Controller::Search;
use Mojo::Base 'Mojolicious::Controller';
sub web {
my $c = shift;
return unless $c->openapi->valid_input;
my $args = $c->validation->output;
my @search = ( @{$args}{qw/q from size/} );
push @search, $args->{collapsed} if exists $args->{collapsed};
my $results = $c->model->search->search_web(@search);
return $c->render( json => $results );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- extract the validated
parameters into a hashref for
use
Mojolicious Controller
Configure the controller to use the OpenAPI plugin to validate and extract parameters.
package MetaCPAN::API::Controller::Search;
use Mojo::Base 'Mojolicious::Controller';
sub web {
my $c = shift;
return unless $c->openapi->valid_input;
my $args = $c->validation->output;
my @search = ( @{$args}{qw/q from size/} );
push @search, $args->{collapsed} if exists $args->{collapsed};
my $results = $c->model->search->search_web(@search);
return $c->render( json => $results );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- now that the parameters are
available, do the work
Mojolicious Controller
Configure the controller to use the OpenAPI plugin to validate and extract parameters.
package MetaCPAN::API::Controller::Search;
use Mojo::Base 'Mojolicious::Controller';
sub web {
my $c = shift;
return unless $c->openapi->valid_input;
my $args = $c->validation->output;
my @search = ( @{$args}{qw/q from size/} );
push @search, $args->{collapsed} if exists $args->{collapsed};
my $results = $c->model->search->search_web(@search);
return $c->render( json => $results );
}
1;
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
Advanced Definitions
Reusing definitions through references
Use $ref as a relative pointer to a file to include.
results:
title: Results
type: array
items:
$ref: "../definitions/results.yml#/search_result_items"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The specification allows for reuse
by means of
JSON references.
- The $ref attribute is a relative
pointer to the file
- and the section of the file to find it
in (again separated by #)
Reusing definitions through references
Use $ref as a relative pointer to a file to include.
results:
title: Results
type: array
items:
$ref: "../definitions/results.yml#/search_result_items"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- excellent use for references
is error definitions
Reusing definitions through references
Reusing error definitions.
responses:
200:
description: Release response
schema:
type: object
properties:
name:
type: string
default:
description: "unexpected error"
schema:
$ref: "../definitions/common.yml#/ErrorModel"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- meanings of error codes are
fairly static
- use references to reduce
repitition
Reusing definitions through references
Reusing error definitions.
responses:
200:
description: Release response
schema:
type: object
properties:
name:
type: string
default:
description: "unexpected error"
schema:
$ref: "../definitions/common.yml#/ErrorModel"
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
Reusing definitions through references
Some gotchas
• The v2.0 specification does have restrictions on where
references can be use, which does cause repetition in the
specification file.
• The v3.0 specification has corrected these issues, and also
allows for http references.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- There are times that a property of an
object might be null.
- In the MetaCPAN API the favourite count
may either be an integer representing
how many people have favourited the
distribution, or null.
- Using a list for the property type allows
the property to contain both.
Might be null
favorites:
type:
- integer
- null
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- start small
- spec doesn't have to include
everything
Words of Advice
The entire specification doesn’t need to be complete in order
to get OpenAPI up and running. When documenting an
existing API, it’s possible to begin with one portion of the API.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- With MetaCPAN we started
with the search endpoints.
Words of Advice
Using an object as a response value while developing can
help while the full specification is being written. Add
properties to the response as time permits.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
- The import part is to get started
- organization will likely change
as the specification is fleshed out
- the API may be "static", but the
specification contents can
evolve
Words of Advice
Refactoring the specification to reuse, organize and
consolidate is possible after publishing.
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
Further Reading
• MetaCPAN spec file
https://github.com/metacpan/metacpan-api/blob/master/root/static/v1.yml
• MetaCPAN API documentation here
https://fastapi.metacpan.org/static/index.html
• OpenAPI Specification repository
https://github.com/OAI/OpenAPI-Specification
includes full documentation and many examples of varying levels of details.
• ReDoc
https://github.com/Rebilly/ReDoc
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
DEMO?
Demo URLs
• MetaCPAN ReDoc API Documentation
• Search Web
• Autocomplete Suggest for Moose
• Validation Failure
MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti

More Related Content

What's hot

Php Presentation
Php PresentationPhp Presentation
Php Presentation
Manish Bothra
 
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
ruyalarcon
 
170517 damien gérard framework facebook
170517 damien gérard   framework facebook170517 damien gérard   framework facebook
170517 damien gérard framework facebook
Geeks Anonymes
 
PHP 7 Crash Course - php[world] 2015
PHP 7 Crash Course - php[world] 2015PHP 7 Crash Course - php[world] 2015
PHP 7 Crash Course - php[world] 2015
Colin O'Dell
 
Laravel 5
Laravel 5Laravel 5
Laravel 5
Sudip Simkhada
 
Xml+messaging+with+soap
Xml+messaging+with+soapXml+messaging+with+soap
Xml+messaging+with+soap
Aravindharamanan S
 
Red5 - PHUG Workshops
Red5 - PHUG WorkshopsRed5 - PHUG Workshops
Red5 - PHUG Workshops
Brendan Sera-Shriar
 
Intro to flask2
Intro to flask2Intro to flask2
Intro to flask2
Mohamed Essam
 
Developing web applications
Developing web applicationsDeveloping web applications
Developing web applications
salissal
 

What's hot (9)

Php Presentation
Php PresentationPhp Presentation
Php Presentation
 
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
Fulfilling the Hypermedia Constraint via HTTP OPTIONS, The HTTP Vocabulary In...
 
170517 damien gérard framework facebook
170517 damien gérard   framework facebook170517 damien gérard   framework facebook
170517 damien gérard framework facebook
 
PHP 7 Crash Course - php[world] 2015
PHP 7 Crash Course - php[world] 2015PHP 7 Crash Course - php[world] 2015
PHP 7 Crash Course - php[world] 2015
 
Laravel 5
Laravel 5Laravel 5
Laravel 5
 
Xml+messaging+with+soap
Xml+messaging+with+soapXml+messaging+with+soap
Xml+messaging+with+soap
 
Red5 - PHUG Workshops
Red5 - PHUG WorkshopsRed5 - PHUG Workshops
Red5 - PHUG Workshops
 
Intro to flask2
Intro to flask2Intro to flask2
Intro to flask2
 
Developing web applications
Developing web applicationsDeveloping web applications
Developing web applications
 

Similar to MetaCPAN, Mojolicious and OpenAPI

Schema-First API Design
Schema-First API DesignSchema-First API Design
Schema-First API Design
Yos Riady
 
2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards
APIsecure_ Official
 
Introducing OpenAPI Version 3.1
Introducing OpenAPI Version 3.1Introducing OpenAPI Version 3.1
Introducing OpenAPI Version 3.1
SmartBear
 
Dead Simple APIs with OpenAPI
Dead Simple APIs with OpenAPIDead Simple APIs with OpenAPI
Dead Simple APIs with OpenAPI
Chris Tankersley
 
APIdays Paris 2019 Backend is the new frontend by Antoine Cheron
APIdays Paris 2019 Backend is the new frontend by Antoine CheronAPIdays Paris 2019 Backend is the new frontend by Antoine Cheron
APIdays Paris 2019 Backend is the new frontend by Antoine Cheron
apidays
 
Apigility – Lightning Fast API Development - OSSCamp 2014
Apigility – Lightning Fast API Development - OSSCamp 2014 Apigility – Lightning Fast API Development - OSSCamp 2014
Apigility – Lightning Fast API Development - OSSCamp 2014
OSSCube
 
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0 OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
Scott Lee Davis
 
REST API Basics
REST API BasicsREST API Basics
REST API Basics
Tharindu Weerasinghe
 
Enforcing API Design Rules for High Quality Code Generation
Enforcing API Design Rules for High Quality Code GenerationEnforcing API Design Rules for High Quality Code Generation
Enforcing API Design Rules for High Quality Code Generation
Tim Burks
 
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
chbornet
 
Developing Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & PythonDeveloping Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & Python
SmartBear
 
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
Evan Mullins
 
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
Evan Mullins
 
Web Dev 21-01-2024.pptx
Web Dev 21-01-2024.pptxWeb Dev 21-01-2024.pptx
Web Dev 21-01-2024.pptx
PARDHIVANNABATTULA
 
Walter api
Walter apiWalter api
Walter api
Nicholas Schiller
 
API Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIsAPI Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIs
Tom Johnson
 
The Open Web
The Open WebThe Open Web
The Open Web
Lachlan Hardy
 
Use drupal 8 as a framework the romance recalibration
Use drupal 8 as a framework   the romance recalibrationUse drupal 8 as a framework   the romance recalibration
Use drupal 8 as a framework the romance recalibration
Kevin Wenger
 
High quality ap is with api platform
High quality ap is with api platformHigh quality ap is with api platform
High quality ap is with api platform
Nelson Kopliku
 
PyCon Korea 2019 REST API Document Generation
PyCon Korea 2019 REST API Document GenerationPyCon Korea 2019 REST API Document Generation
PyCon Korea 2019 REST API Document Generation
용선 이
 

Similar to MetaCPAN, Mojolicious and OpenAPI (20)

Schema-First API Design
Schema-First API DesignSchema-First API Design
Schema-First API Design
 
2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards
 
Introducing OpenAPI Version 3.1
Introducing OpenAPI Version 3.1Introducing OpenAPI Version 3.1
Introducing OpenAPI Version 3.1
 
Dead Simple APIs with OpenAPI
Dead Simple APIs with OpenAPIDead Simple APIs with OpenAPI
Dead Simple APIs with OpenAPI
 
APIdays Paris 2019 Backend is the new frontend by Antoine Cheron
APIdays Paris 2019 Backend is the new frontend by Antoine CheronAPIdays Paris 2019 Backend is the new frontend by Antoine Cheron
APIdays Paris 2019 Backend is the new frontend by Antoine Cheron
 
Apigility – Lightning Fast API Development - OSSCamp 2014
Apigility – Lightning Fast API Development - OSSCamp 2014 Apigility – Lightning Fast API Development - OSSCamp 2014
Apigility – Lightning Fast API Development - OSSCamp 2014
 
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0 OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
OWASP PDX May 2016 : Scanning with Swagger (OAS) 2.0
 
REST API Basics
REST API BasicsREST API Basics
REST API Basics
 
Enforcing API Design Rules for High Quality Code Generation
Enforcing API Design Rules for High Quality Code GenerationEnforcing API Design Rules for High Quality Code Generation
Enforcing API Design Rules for High Quality Code Generation
 
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
JHipster Conf 2018 : Connect your JHipster apps to the world of APIs with Ope...
 
Developing Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & PythonDeveloping Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & Python
 
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Raleigh 2016 - WP API, What is it good for? Absolutely Everything!
 
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
WordCamp Birmingham 2016 - WP API, What is it good for? Absolutely Everything!
 
Web Dev 21-01-2024.pptx
Web Dev 21-01-2024.pptxWeb Dev 21-01-2024.pptx
Web Dev 21-01-2024.pptx
 
Walter api
Walter apiWalter api
Walter api
 
API Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIsAPI Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIs
 
The Open Web
The Open WebThe Open Web
The Open Web
 
Use drupal 8 as a framework the romance recalibration
Use drupal 8 as a framework   the romance recalibrationUse drupal 8 as a framework   the romance recalibration
Use drupal 8 as a framework the romance recalibration
 
High quality ap is with api platform
High quality ap is with api platformHigh quality ap is with api platform
High quality ap is with api platform
 
PyCon Korea 2019 REST API Document Generation
PyCon Korea 2019 REST API Document GenerationPyCon Korea 2019 REST API Document Generation
PyCon Korea 2019 REST API Document Generation
 

Recently uploaded

High performance Serverless Java on AWS- GoTo Amsterdam 2024
High performance Serverless Java on AWS- GoTo Amsterdam 2024High performance Serverless Java on AWS- GoTo Amsterdam 2024
High performance Serverless Java on AWS- GoTo Amsterdam 2024
Vadym Kazulkin
 
inQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
inQuba Webinar Mastering Customer Journey Management with Dr Graham HillinQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
inQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
LizaNolte
 
ScyllaDB Tablets: Rethinking Replication
ScyllaDB Tablets: Rethinking ReplicationScyllaDB Tablets: Rethinking Replication
ScyllaDB Tablets: Rethinking Replication
ScyllaDB
 
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
Pitangent Analytics & Technology Solutions Pvt. Ltd
 
A Deep Dive into ScyllaDB's Architecture
A Deep Dive into ScyllaDB's ArchitectureA Deep Dive into ScyllaDB's Architecture
A Deep Dive into ScyllaDB's Architecture
ScyllaDB
 
"Frontline Battles with DDoS: Best practices and Lessons Learned", Igor Ivaniuk
"Frontline Battles with DDoS: Best practices and Lessons Learned",  Igor Ivaniuk"Frontline Battles with DDoS: Best practices and Lessons Learned",  Igor Ivaniuk
"Frontline Battles with DDoS: Best practices and Lessons Learned", Igor Ivaniuk
Fwdays
 
Introduction of Cybersecurity with OSS at Code Europe 2024
Introduction of Cybersecurity with OSS  at Code Europe 2024Introduction of Cybersecurity with OSS  at Code Europe 2024
Introduction of Cybersecurity with OSS at Code Europe 2024
Hiroshi SHIBATA
 
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
Edge AI and Vision Alliance
 
Northern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
Northern Engraving | Modern Metal Trim, Nameplates and Appliance PanelsNorthern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
Northern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
Northern Engraving
 
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdfHow to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
Chart Kalyan
 
Northern Engraving | Nameplate Manufacturing Process - 2024
Northern Engraving | Nameplate Manufacturing Process - 2024Northern Engraving | Nameplate Manufacturing Process - 2024
Northern Engraving | Nameplate Manufacturing Process - 2024
Northern Engraving
 
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
Alex Pruden
 
QA or the Highway - Component Testing: Bridging the gap between frontend appl...
QA or the Highway - Component Testing: Bridging the gap between frontend appl...QA or the Highway - Component Testing: Bridging the gap between frontend appl...
QA or the Highway - Component Testing: Bridging the gap between frontend appl...
zjhamm304
 
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectorsConnector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
DianaGray10
 
Principle of conventional tomography-Bibash Shahi ppt..pptx
Principle of conventional tomography-Bibash Shahi ppt..pptxPrinciple of conventional tomography-Bibash Shahi ppt..pptx
Principle of conventional tomography-Bibash Shahi ppt..pptx
BibashShahi
 
Apps Break Data
Apps Break DataApps Break Data
Apps Break Data
Ivo Velitchkov
 
Main news related to the CCS TSI 2023 (2023/1695)
Main news related to the CCS TSI 2023 (2023/1695)Main news related to the CCS TSI 2023 (2023/1695)
Main news related to the CCS TSI 2023 (2023/1695)
Jakub Marek
 
Christine's Product Research Presentation.pptx
Christine's Product Research Presentation.pptxChristine's Product Research Presentation.pptx
Christine's Product Research Presentation.pptx
christinelarrosa
 
Christine's Supplier Sourcing Presentaion.pptx
Christine's Supplier Sourcing Presentaion.pptxChristine's Supplier Sourcing Presentaion.pptx
Christine's Supplier Sourcing Presentaion.pptx
christinelarrosa
 
Demystifying Knowledge Management through Storytelling
Demystifying Knowledge Management through StorytellingDemystifying Knowledge Management through Storytelling
Demystifying Knowledge Management through Storytelling
Enterprise Knowledge
 

Recently uploaded (20)

High performance Serverless Java on AWS- GoTo Amsterdam 2024
High performance Serverless Java on AWS- GoTo Amsterdam 2024High performance Serverless Java on AWS- GoTo Amsterdam 2024
High performance Serverless Java on AWS- GoTo Amsterdam 2024
 
inQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
inQuba Webinar Mastering Customer Journey Management with Dr Graham HillinQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
inQuba Webinar Mastering Customer Journey Management with Dr Graham Hill
 
ScyllaDB Tablets: Rethinking Replication
ScyllaDB Tablets: Rethinking ReplicationScyllaDB Tablets: Rethinking Replication
ScyllaDB Tablets: Rethinking Replication
 
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
Crafting Excellence: A Comprehensive Guide to iOS Mobile App Development Serv...
 
A Deep Dive into ScyllaDB's Architecture
A Deep Dive into ScyllaDB's ArchitectureA Deep Dive into ScyllaDB's Architecture
A Deep Dive into ScyllaDB's Architecture
 
"Frontline Battles with DDoS: Best practices and Lessons Learned", Igor Ivaniuk
"Frontline Battles with DDoS: Best practices and Lessons Learned",  Igor Ivaniuk"Frontline Battles with DDoS: Best practices and Lessons Learned",  Igor Ivaniuk
"Frontline Battles with DDoS: Best practices and Lessons Learned", Igor Ivaniuk
 
Introduction of Cybersecurity with OSS at Code Europe 2024
Introduction of Cybersecurity with OSS  at Code Europe 2024Introduction of Cybersecurity with OSS  at Code Europe 2024
Introduction of Cybersecurity with OSS at Code Europe 2024
 
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
“Temporal Event Neural Networks: A More Efficient Alternative to the Transfor...
 
Northern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
Northern Engraving | Modern Metal Trim, Nameplates and Appliance PanelsNorthern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
Northern Engraving | Modern Metal Trim, Nameplates and Appliance Panels
 
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdfHow to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
How to Interpret Trends in the Kalyan Rajdhani Mix Chart.pdf
 
Northern Engraving | Nameplate Manufacturing Process - 2024
Northern Engraving | Nameplate Manufacturing Process - 2024Northern Engraving | Nameplate Manufacturing Process - 2024
Northern Engraving | Nameplate Manufacturing Process - 2024
 
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
zkStudyClub - LatticeFold: A Lattice-based Folding Scheme and its Application...
 
QA or the Highway - Component Testing: Bridging the gap between frontend appl...
QA or the Highway - Component Testing: Bridging the gap between frontend appl...QA or the Highway - Component Testing: Bridging the gap between frontend appl...
QA or the Highway - Component Testing: Bridging the gap between frontend appl...
 
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectorsConnector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
Connector Corner: Seamlessly power UiPath Apps, GenAI with prebuilt connectors
 
Principle of conventional tomography-Bibash Shahi ppt..pptx
Principle of conventional tomography-Bibash Shahi ppt..pptxPrinciple of conventional tomography-Bibash Shahi ppt..pptx
Principle of conventional tomography-Bibash Shahi ppt..pptx
 
Apps Break Data
Apps Break DataApps Break Data
Apps Break Data
 
Main news related to the CCS TSI 2023 (2023/1695)
Main news related to the CCS TSI 2023 (2023/1695)Main news related to the CCS TSI 2023 (2023/1695)
Main news related to the CCS TSI 2023 (2023/1695)
 
Christine's Product Research Presentation.pptx
Christine's Product Research Presentation.pptxChristine's Product Research Presentation.pptx
Christine's Product Research Presentation.pptx
 
Christine's Supplier Sourcing Presentaion.pptx
Christine's Supplier Sourcing Presentaion.pptxChristine's Supplier Sourcing Presentaion.pptx
Christine's Supplier Sourcing Presentaion.pptx
 
Demystifying Knowledge Management through Storytelling
Demystifying Knowledge Management through StorytellingDemystifying Knowledge Management through Storytelling
Demystifying Knowledge Management through Storytelling
 

MetaCPAN, Mojolicious and OpenAPI

  • 2. - During meta::hack 3 work with Joel Berger on integrating/documenting OpenAPI with the MetaCPAN API via Mojolicious. Overview of how OpenAPI was integrated into MetaCPAN with Mojolicious. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 3. - The OpenAPI Specification originated as the Swagger specification - renamed to separate the API description format (OpenAPI) from the open source tooling (Swagger). - used to provide documentation to an existing API, or when creating a new one. - For MetaCPAN API, we set out to provide documentation to the existing API, but through discussion, validation and driving the API calls as well. What is OpenAPI? OpenAPI is a specification for designing, documenting, validating and driving your RESTful API. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 4. - Most importantly, the OpenAPI spec becomes the one source of truth for the API - documentation - routing - validation - responses One Source of Truth
  • 5. - There are discovery tools that will assist in writing the specification. - We chose to write the definition by hand (in vim of course) and use tools to generate the documentation and to integrate the specification into MetaCPAN. The Tools
  • 6. - Interactive map that shows each layers options - it includes acceptable values and documentation OpenAPI Map The OpenAPI Map is an interactive site to aid in working with the OpenAPI Specification. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 7. - ReDoc creates an interactive page providing documentation and examples based on the details provided in the OpenAPI specification file. - this is what creates the documentation for your API ReDoc ReDoc — OpenAPI/Swagger-generated API Reference Documentation MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 8. — OpenAPI / Swagger plugin for Mojolicious - Author: Jan Henning Thorsen - Reads the OpenAPI specification file and adds the appropriate routes and validations for your Mojolicious based application. Mojolicious::Plugin::OpenAPI Mojolicious::Plugin::OpenAPI — OpenAPI / Swagger plugin for Mojolicious MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 9. - Author: Jan Henning Thorsen - Integrated into the Mojolicious::Plugin::OpenAPI module - provides the input and output validation - providing validation for the specification file itself. JSON::Validator JSON::Validator — Validate data against a JSON schema MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 11. - going to start with setting up ReDoc as it is quite simple to configure ReDoc ReDoc includes a HTML template to be served as a static file for customizing how the documentation is displayed. <!DOCTYPE html> <html> <head> <title>MetaCPAN API</title> <!-- needed for adaptive design --> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"> <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet"> <!-- ReDoc doesn't change outer page styles --> <style> body { margin: 0; padding: 0; } </style> </head> <body> <redoc spec-url="./v1.yml" lazy-rendering="1" required-props-first="1" path-in-middle-panel="1"></redoc> <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> </body> </html> MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 12. - The import part here is the redoc tag and the spec- url - the html and spec file must be in a location that the server will serve static files from ReDoc ReDoc includes a HTML template to be served as a static file for customizing how the documentation is displayed. <!DOCTYPE html> <html> <head> <title>MetaCPAN API</title> <!-- needed for adaptive design --> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"> <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet"> <!-- ReDoc doesn't change outer page styles --> <style> body { margin: 0; padding: 0; } </style> </head> <body> <redoc spec-url="./v1.yml" lazy-rendering="1" required-props-first="1" path-in-middle-panel="1"></redoc> <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> </body> </html> MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 13. - specification files can be quite long, breaking it down for demonstration purposes - later I'll show how to organize better - specification can be in either JSON or YAML - YAML supports multiline attribute values making it much easier to read and write with less formatting The OpenAPI Specification File The specification file is v1.yml swagger: "2.0" info: version: "1.0.0" title: "MetaCPAN API" basePath: "/v1" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 14. - Define the version of the OpenAPI spec to use. - Version 2.0 still uses swagger as the key The OpenAPI Specification File The specification file is v1.yml swagger: "2.0" info: version: "1.0.0" title: "MetaCPAN API" basePath: "/v1" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 15. - General information about the API The OpenAPI Specification File The specification file is v1.yml swagger: "2.0" info: version: "1.0.0" title: "MetaCPAN API" basePath: "/v1" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 16. - common path shared throughout the API The OpenAPI Specification File The specification file is v1.yml swagger: "2.0" info: version: "1.0.0" title: "MetaCPAN API" basePath: "/v1" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 17. - configuration of API paths are contained in sections named after the URL path to access them Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 18. - the URL path to access this portion of the API - the basePath is automatically prefixed to the URL on consumption Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 19. - The HTTP methods that the endpoint accepts Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 20. - A unique identifier for the method Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 21. - an extension attribute used by Mojolicious - This attribute points to the name of the class in the application and the method to call separated by # Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 22. - A description of the API Endpoint Defining an Endpoint Each of the paths available to the API are defined within the paths object. paths: /search/web: get: operationId: search_web x-mojo-to: Search#web summary: Perform API search in the same fashion as the Web UI MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 23. - The parameters that the HTTP method accepts Defining Parameters Each method can define its own parameters. parameters: - name: q in: query description: | The query search term. If the search term contains a term with the tags `dist:` or `module:` results will be in expanded form, otherwise collapsed form. See also `collapsed` type: string # Define the attribute as required required: true - name: from in: query description: The offset to use in the result set type: integer default: 0 - name: size in: query description: Number of results per page type: integer default: 20 - name: collapsed in: query description: | Force a collapsed even when searching for a particular distribution or module name. type: boolean MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 24. - The parameter attribute identifies the parameters and accepts an array of objects. Defining Parameters Each method can define its own parameters. parameters: - name: q in: query description: | The query search term. If the search term contains a term with the tags `dist:` or `module:` results will be in expanded form, otherwise collapsed form. See also `collapsed` type: string # Define the attribute as required required: true MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 25. - In this instance the parameter name is q - The location to parse the parameter from is from the query - parameters are accessible from within Mojolicious by name (I'll show the calls later) - in defines the location of the parameter: - this instance is query - header - path - formData - body Defining Parameters Each method can define its own parameters. parameters: - name: q in: query description: | The query search term. If the search term contains a term with the tags `dist:` or `module:` results will be in expanded form, otherwise collapsed form. See also `collapsed` type: string required: true MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 26. - Document what the parameter is. - This example uses the YAML HEREDOC syntax to make the description easier to read and write. - using the HEREDOC also allows for paragraph separation in the documentation Defining Parameters Each method can define its own parameters. parameters: - name: q in: query description: | The query search term. If the search term contains a term with the tags `dist:` or `module:` results will be in expanded form, otherwise collapsed form. See also `collapsed` type: string required: true MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 27. - The type of the value that the API accepts: - array - boolean - integer - number - null - object - string - required does what it says. Defining Parameters Each method can define its own parameters. parameters: - name: q in: query description: | The query search term. If the search term contains a term with the tags `dist:` or `module:` results will be in expanded form, otherwise collapsed form. See also `collapsed` type: string required: true MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 28. Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 29. - the responses attribute contains objects keyed on the HTTP response code or the keyword default Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 30. - response codes are defined by HTTP status numbers Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 31. - The schema defines what the result will look like Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 32. - The schema defines what the result will look like - objects - primitives - arrays Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 33. - While items can be further broken into properties per item, - type object is a catch all Defining the Response The OpenAPI specification allows you to define each response to a method call, this includes both specific and generic error handling. responses: 200: description: Search response schema: type: object properties: total: type: integer took: type: number collapsed: type: boolean results: title: Results type: array items: type: object MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 34. - I'll admit, this is taken right from the error definitions from the OpenAPI repository - https://github.com/OAI/ OpenAPI-Specification/blob/ master/examples/v2.0/yaml/ petstore.yaml#L92-L101 Error Definitions Error messages can be defined by HTTP status codes or default. default: description: "unexpected error" schema: type: object required: - code - message properties: code: type: integer format: int32 message: type: string MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 35. - Up until now all this work is defining the API spec - now to use it Hooking in Mojolicious
  • 36. - Additions to the Mojolicious application consist of enabling the plugin Mojolicious Application package MetaCPAN::API; use Mojo::Base 'Mojolicious'; sub startup { $self->plugin( 'OpenAPI' => { url => $self->home->rel_file('root/static/v1.yml') } ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 37. - configures the API plugin - url points to the OpenAPI specification file Mojolicious Application package MetaCPAN::API; use Mojo::Base 'Mojolicious'; sub startup { $self->plugin( 'OpenAPI' => { url => $self->home->rel_file('root/static/v1.yml') } ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 38. - this is an example of the Search web interface from MetaCPAN - as you can see there's not a lot of code to the method Mojolicious Controller Configure the controller to use the OpenAPI plugin to validate and extract parameters. package MetaCPAN::API::Controller::Search; use Mojo::Base 'Mojolicious::Controller'; sub web { my $c = shift; return unless $c->openapi->valid_input; my $args = $c->validation->output; my @search = ( @{$args}{qw/q from size/} ); push @search, $args->{collapsed} if exists $args->{collapsed}; my $results = $c->model->search->search_web(@search); return $c->render( json => $results ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 39. - validate the parameters against the specification - return undef triggers an error, resulting in a message specifying the validation issue Mojolicious Controller Configure the controller to use the OpenAPI plugin to validate and extract parameters. package MetaCPAN::API::Controller::Search; use Mojo::Base 'Mojolicious::Controller'; sub web { my $c = shift; return unless $c->openapi->valid_input; my $args = $c->validation->output; my @search = ( @{$args}{qw/q from size/} ); push @search, $args->{collapsed} if exists $args->{collapsed}; my $results = $c->model->search->search_web(@search); return $c->render( json => $results ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 40. - extract the validated parameters into a hashref for use Mojolicious Controller Configure the controller to use the OpenAPI plugin to validate and extract parameters. package MetaCPAN::API::Controller::Search; use Mojo::Base 'Mojolicious::Controller'; sub web { my $c = shift; return unless $c->openapi->valid_input; my $args = $c->validation->output; my @search = ( @{$args}{qw/q from size/} ); push @search, $args->{collapsed} if exists $args->{collapsed}; my $results = $c->model->search->search_web(@search); return $c->render( json => $results ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 41. - now that the parameters are available, do the work Mojolicious Controller Configure the controller to use the OpenAPI plugin to validate and extract parameters. package MetaCPAN::API::Controller::Search; use Mojo::Base 'Mojolicious::Controller'; sub web { my $c = shift; return unless $c->openapi->valid_input; my $args = $c->validation->output; my @search = ( @{$args}{qw/q from size/} ); push @search, $args->{collapsed} if exists $args->{collapsed}; my $results = $c->model->search->search_web(@search); return $c->render( json => $results ); } 1; MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 43. Reusing definitions through references Use $ref as a relative pointer to a file to include. results: title: Results type: array items: $ref: "../definitions/results.yml#/search_result_items" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 44. - The specification allows for reuse by means of JSON references. - The $ref attribute is a relative pointer to the file - and the section of the file to find it in (again separated by #) Reusing definitions through references Use $ref as a relative pointer to a file to include. results: title: Results type: array items: $ref: "../definitions/results.yml#/search_result_items" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 45. - excellent use for references is error definitions Reusing definitions through references Reusing error definitions. responses: 200: description: Release response schema: type: object properties: name: type: string default: description: "unexpected error" schema: $ref: "../definitions/common.yml#/ErrorModel" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 46. - meanings of error codes are fairly static - use references to reduce repitition Reusing definitions through references Reusing error definitions. responses: 200: description: Release response schema: type: object properties: name: type: string default: description: "unexpected error" schema: $ref: "../definitions/common.yml#/ErrorModel" MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 47. Reusing definitions through references Some gotchas • The v2.0 specification does have restrictions on where references can be use, which does cause repetition in the specification file. • The v3.0 specification has corrected these issues, and also allows for http references. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 48. - There are times that a property of an object might be null. - In the MetaCPAN API the favourite count may either be an integer representing how many people have favourited the distribution, or null. - Using a list for the property type allows the property to contain both. Might be null favorites: type: - integer - null MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 49. - start small - spec doesn't have to include everything Words of Advice The entire specification doesn’t need to be complete in order to get OpenAPI up and running. When documenting an existing API, it’s possible to begin with one portion of the API. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 50. - With MetaCPAN we started with the search endpoints. Words of Advice Using an object as a response value while developing can help while the full specification is being written. Add properties to the response as time permits. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 51. - The import part is to get started - organization will likely change as the specification is fleshed out - the API may be "static", but the specification contents can evolve Words of Advice Refactoring the specification to reuse, organize and consolidate is possible after publishing. MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 52. Further Reading • MetaCPAN spec file https://github.com/metacpan/metacpan-api/blob/master/root/static/v1.yml • MetaCPAN API documentation here https://fastapi.metacpan.org/static/index.html • OpenAPI Specification repository https://github.com/OAI/OpenAPI-Specification includes full documentation and many examples of varying levels of details. • ReDoc https://github.com/Rebilly/ReDoc MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti
  • 53. DEMO?
  • 54. Demo URLs • MetaCPAN ReDoc API Documentation • Search Web • Autocomplete Suggest for Moose • Validation Failure MetaCPAN, Mojolicious and OpenAPI // Toronto Perl Mongers // Shawn Sorichetti