Draft OpenAPI specs v3.0.0 for MetaCPAN API

[jackdeguest]

I have produced for your review this draft MetaCPAN specifications based on the information I could collect from the documentations and the code.
I think this is helpful in providing further clarity on the MetaCPAN API.

[oalders]

I haven't had a chance to look at this yet. We did get the beginnings of swagger docs in https://github.com/metacpan/metacpan-api/pull/862/files

It looks like, for example, there's something here: https://fastapi.metacpan.org/v1/static/v1.yml

Maybe @jberger remembers more about it?

[oalders]

Thanks, @jackdeguest. I apologize for how long this has languished here. How did you aggregate this data?

[jackdeguest]

Thanks, @jackdeguest. I apologize for how long this has languished here. How did you aggregate this data?

Very patiently by reading your documentation, reading the code and using your API playground. It took me quite a bit of time.

[briandfoy]

I just saw https://blogs.perl.org/users/karjala/2026/01/perlmodulesnet-is-down-for-1-2-weeks.html , which says:

Because metacpan.org changes its API in a major way, and I need to change this site accesses it.

Is this pull request what that post is referring to? Is there a roadmap somewhere for the transition?

[oalders]

No, the backend just got a major bump. This spec was helpfully put together by @jackdeguest but I think nobody has had the bandwidth to establish how correct it is.

Ideally we would have had two backends running in parallel or even given more notice about the shift but we are pretty constrained people-wise and have literally been working towards this for years. @haarg did a bunch of work to make our endpoints continue to work, but people who have crafted custom queries will need to make some changes.

The title on #metacpan right now is:

ES Upgraded 2->8 on Mon 5th Jan, some syntax changes ( "bool => { must => [ ... ] }" instead of "and => [ ... ]" ) - New MetaCPAN::Client available Dashboard: https://p.datadoghq.eu/sb/c2941b7b-37bb-11f0-94e3-32bf19abf102-744ae84f98611bfd6781365a482e2155 Using the API? https://github.com/metacpan/metacpan-api/wiki/fastapi-Consumers

So, it's not ideal, but this was a way forward that was doable on our end, with some unfortunate 3rd party disruptions. With more resources we could have done something much more defensive, but this was the best way to move things forward without abusing the free hosting on two different versions of Elasticsearch that Elastic is giving us.