(Updated) Grant Proposal: General Perl OpenAPI Validator / Interpreter
Thu, 08-Oct-2020 by
Jason A. Crome
edit post
< - cromedome)
# Synopsis
Develop a clean and easy interface for managing OpenAPI 3.x schemas.
# Proposal
OpenAPI is a format that makes use of the JSON-Schema specification to communicate what a web API can do in a machine-readable way. The current module that is most active for JSON-Schema support in Perl is JSON::Validator.
The feeling in the community is that the JSON::Validator interface is difficult to work with. This is possibly because it covers a broader set of applications than solely OpenAPI, and thus doesn't provide what people might consider to be logical functions when their focus is an API.
The OpenAPI namespace will therefore contain functions specifically aimed at OpenAPI and the normal applications for it (for example, knowing that it will be used with HTTP and paths lets us write functions to use the module in those terms).
We propose to do this by
- Contributing to existing modules, chiefly JSON::Validator, which already has OpenAPI functionality at an experimental level but has known limitations.
- Use the OpenAPI namespace to create an interface for simple, user-friendly interactions with OpenAPI 3.1 schemas. This will include the following steps:
- Specification and design to outline what the module will comprise
- Producing the actual functionality for the module
- Testing to ensure that the module works as expected
# Deliverables
- A satisfactory completion of the implementation of OpenAPI 3.x in JSON::Validator
- At the time of writing, Karen Etheridge has the only implementation of OpenAPI 3.1 on CPAN; JSON::Validator has experimental 3.0 support and will need 3.1 support.
- A module called OpenAPI specifically geared towards creating APIs
- A highly-discoverable entrypoint into CPAN for people wanting to work with OpenAPI and Perl
- An extensively documented namespace that allows new users and old to quickly get working with OpenAPI
- Signposting to other modules that implement relevant behaviour
- Module interface designed with community input
- Extensive automated tests
# Schedule
To be completed within 10 weeks of start of work.
# Project team
## Developers
- Paul G Webster / OpusVL
I am a senior developer at OpusVL, an opensource focussed and perl supporting company that has developed software in use in industries as diverse from one another as medical/healthcare, biometrics and sales/auctions for the DVLA.
I have been developing in perl since October of 2002, where it was present in the base of the FreeBSD operating system and required for building its userland and kernel.
I hold a degree in computer science from the University of Lincoln and aside from my work with perl I am actively participating in technical documentation and creation of learning materials for FreeBSD as well as an ongoing effort to develop a language agnostic microservices protocol.
- Alastair Douglas
Well known in the community, having joined in 2008 and remained active since. Actively used Perl throughout, even when not employed as a Perl developer.
I have extensive experience in designing APIs and telling other people off for doing them wrong. After I delved into the OpenAPI spec for a project I took control of the OpenAPI namespace on CPAN with the intention of Doing It Right, but have until now not had the opportunity to make something of it.
## Documentor / technical writer
- Laurence Bogle
A technical writer with over a decade of experience in writing user guides and technical documents for both hardware and software. An MEng in Electronic and Electrical Engineering, plus lots of time spent working with developers has ensured a strong technical background.
# Costs
- Elapsed time: 10 calendar weeks
- Total cost: $8370 (186 hours @$45 / hr)
]]>
Comments (6)
Can you give some high-level examples of some usecases you would like to implement/solve?
"The feeling in the community is that the JSON::Validator interface is difficult to work with." - can you provide more information on this because a) it feels like massively begging the question, and b) i don't believe this is the case.
There has been little community involvement in this thing except for people who appear to be heavily invested in the existing modules. The only third-party who had an opinion requested a reworking of the J::V API. This combined with my own experience was enough to suggest that I'm not the only one who struggled with it. I'm troubled by the nitpicking here. If we pretend this sentence wasn't in the proposal, is the proposal invalid? I would argue not.
On the, er, rest of the proposal itself - the OpenAPI-Specification currently has 449 open issues, many of which pertain to details of the spec and/or future requests for features.
My own experience, in working with RESTful APIs for at least a decade, is that it's not possible to have all functions for all users - we have seen this multiple times, OAuth2 for example, and despite OpenAPI's ambitions to standardise this they are discovering that it is not possible.
It's the reason all of this stuff moves so quickly and any successful attempts become a dogpile. I absolutely guarantee that the timeline of 10 weeks is massively optimisic, and even *if* that is achieved the implementation will be out of date within a few months. This is something you are going to have to support and maintain for the next *decade*.
"There has been little community involvement in this thing" - I think the reason behind this is that most people are busy going to work and building applications that again pays their salary. J::V have had about 25 contributors since it was launched in 2015, but I have been the main driver for making sure this module supports the different versions of JSON-Schema - though the latest draft is currently not supported. I don't know who this "third party" you are referring to is, but I am open to changing the API. Major breakage to the API on the other hand will not be accepted, since there are existing businesses that relies on it. The last refactor (when I adding custom schema classes) took quite some time to make sure it was back compat. Either way, I cannot recall getting a proper request to change the API. To whoever who wants that: Please open an issue, send me an email, or chat with the existing users in #perl-openapi on freenode. Last, I want to say that I don't think it's nitpicking what @leej wrote. I guess we are all in our own bubble here, where I have had a lot of positive feedback on the existing tools, from many Perl programmers. I do consider that the people who gave me that feedback is also part of the community.
JSON::Validator have gotten some updates over the ~weekend... #1 Draft 2019-09: https://github.com/mojolicious/json-validator/issues/181 #2 OpenAPI support: https://github.com/mojolicious/json-validator/issues/227 #3 JSON-Schema-Test-Suite: https://github.com/mojolicious/json-validator/issues/213 #4 https://github.com/mojolicious/json-validator/blob/d27609ff24b221e3804c7f81b070476f11656ba9/Changes#L3-L32
