Topics

New Forge API Endpoints

Nik Anderson
 
Edited

Hello,
 
The Forge team is getting ready to announce new API endpoints in a blog post (draft below), and we wanted to give you all a heads up beforehand. In short, we've added public endpoints for module management, and authentication through API keys.
 
We're planning to add support to the puppet_forge gem for the new endpoints in the future. Does it seem like a possibility for the Blacksmith gem to be updated to use the new API key auth? Anything we can do to help with that?
 
Thanks!
 

Nik Anderson

Software Engineer

Pronouns: he / his

nik.anderson@...

Puppet. The shortest path to better software.
 
 
DRAFT: New Forge API Endpoints for Automating Module Management
 
Fully automating the lifecycle of your Puppet module - it's the stuff dreams are made of. Ok, maybe not so much for the general public, but if you're a module developer, this is an exciting prospect! That's why we're pleased to announce a new collection of Forge API endpoints that allow for complete programmatic module management. What does that mean? It's now possible to log in to your Forge account, create an API key, and use that key to publish, delete, or deprecate any of your modules directly through the Forge API.

## Current publishing options Taking a step or two back, we know there are a lot of module developers out there using [Blacksmith](
https://github.com/voxpupuli/puppet-blacksmith) to publish their modules, so you may be wondering how the new endpoints are an improvement. Blacksmith is a great tool that the Puppet community built in part to fill the gaps in the Forge API. However, some of the prior limitations in the API meant that the publishing flow of the Blacksmith implementation is somewhat less than ideal. For example, since we hadn't yet implemented authentication through API keys, the Blacksmith workflow involves passing a Forge username and password in plain text. This made automated publishing possible, but we’re excited to be able to provide a more standard authentication flow.

## Beyond just publishing Initially we only set out to create a publish endpoint within our v3 namespace for the Forge API. After thinking about the work this would entail and the community needs, we decided it was important to add endpoints for other essential module management tasks as well, namely deletion and deprecation. We ended up adding the following endpoints:
* `POST /v3/releases`
* `DELETE /v3/releases/<release-slug>`
* `DELETE /v3/modules/<module-slug>`
* `PATCH /v3/modules/<module-slug>` (used for module deprecation)

With that, it's possible to automate the entire module lifecycle. Here's an outline of what those steps might look like using `curl`:

To publish a new module release using curl, you can run this command:
~~~ $ curl -D- --request 'POST' '
https://forgeapi.puppet.com/v3/releases' \ -F file=@nkanderson-testmodule-0.1.0.tar.gz \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

And to mark a module release as deleted:
~~~ $ curl -D- --request DELETE \ '
https://forgeapi.puppet.com/v3/releases/nkanderson-testmodule-0.1.0?reason=buggy+release' \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

Deleting the entire module will mark all individual releases as deleted, effectively removing it from the Forge web interface:
~~~ $ curl -D- --request DELETE \ '
https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule?reason=buggy+module' \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

To mark a module as deprecated, use the PATCH method. Note that json data is required to specify the deprecate action. Optional parameters include the reason for deprecation and the slug for a replacement module.
~~~ $ curl -D- --request PATCH '
https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule' \ -d '{"action": "deprecate", "params": {"reason": "No longer maintained", "replacement_slug": "puppetlabs-mysql"} }' \ -H 'Content-Type: application/json' -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

## Bonus: Updated docs! Once we got into the documentation phase for these new endpoints, we realized our Forge API docs could use a little love. So another improvement we made along the way was to update our docs framework. Beyond just a fresh coat of paint, the new docs are clearer and easier to navigate, with added descriptions for a handful of parameters that hadn’t previously surfaced from implementation to the docs. (Screenshot of New Forge API docs)

Want to try it out? Log in to your Forge account, navigate to your user profile page (hint: click your name in the upper right), and on that page you'll see an option to create a new key. Once you've created a key, you're all set to hit the ground running with automating your module management.

 

Hi Nik,
sorry for the late reply. I cannot speak for the whole group, but I'm
not aware of anybody of us that has the resources at the moment to patch
blacksmith. Especially since it's currently not broken. Are you able to
provide a pull request? We're happy to review it!

Cheers, Tim

On 15.05.19 23:56, nik.anderson@... wrote:
[Edited Message Follows]
[Reason: Made the formatting a little less awful]

Hello,

The Forge team is getting ready to announce new API endpoints in a blog post (draft below), and we wanted to give you all a heads up beforehand. In short, we've added public endpoints for module management, and authentication through API keys.

We're planning to add support to the puppet_forge gem for the new endpoints in the future. Does it seem like a possibility for the Blacksmith gem to be updated to use the new API key auth? Anything we can do to help with that?

Thanks!

Nik Anderson

Software Engineer

Pronouns: he / his

nik.anderson@...

Puppet ( https://puppet.com ). The shortest path to better software.

DRAFT: New Forge API Endpoints for Automating Module Management

Fully automating the lifecycle of your Puppet module - it's the stuff dreams are made of. Ok, maybe not so much for the general public, but if you're a module developer, this is an exciting prospect! That's why we're pleased to announce a new collection of Forge API endpoints that allow for complete programmatic module management. What does that mean? It's now possible to log in to your Forge account, create an API key, and use that key to publish, delete, or deprecate any of your modules directly through the Forge API.

## Current publishing options Taking a step or two back, we know there are a lot of module developers out there using [Blacksmith]( https://github.com/voxpupuli/puppet-blacksmith ) to publish their modules, so you may be wondering how the new endpoints are an improvement. Blacksmith is a great tool that the Puppet community built in part to fill the gaps in the Forge API. However, some of the prior limitations in the API meant that the publishing flow of the Blacksmith implementation is somewhat less than ideal. For example, since we hadn't yet implemented authentication through API keys, the Blacksmith workflow involves passing a Forge username and password in plain text. This made automated publishing possible, but we’re excited to be able to provide a more standard authentication flow.

## Beyond just publishing Initially we only set out to create a publish endpoint within our v3 namespace for the Forge API. After thinking about the work this would entail and the community needs, we decided it was important to add endpoints for other essential module management tasks as well, namely deletion and deprecation. We ended up adding the following endpoints:
* `POST /v3/releases`
* `DELETE /v3/releases/<release-slug>`
* `DELETE /v3/modules/<module-slug>`
* `PATCH /v3/modules/<module-slug>` (used for module deprecation)

With that, it's possible to automate the entire module lifecycle. Here's an outline of what those steps might look like using `curl`:

To publish a new module release using curl, you can run this command:
~~~ $ curl -D- --request 'POST' ' https://forgeapi.puppet.com/v3/releases ' \ -F file=@nkanderson-testmodule-0. 1.0.tar.gz \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

And to mark a module release as deleted:
~~~ $ curl -D- --request DELETE \ ' https://forgeapi.puppet.com/v3/releases/nkanderson-testmodule-0.1.0?reason=buggy+release ' \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

Deleting the entire module will mark all individual releases as deleted, effectively removing it from the Forge web interface:
~~~ $ curl -D- --request DELETE \ ' https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule?reason=buggy+module ' \ -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

To mark a module as deprecated, use the PATCH method. Note that json data is required to specify the deprecate action. Optional parameters include the reason for deprecation and the slug for a replacement module.
~~~ $ curl -D- --request PATCH ' https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule ' \ -d '{"action": "deprecate", "params": {"reason": "No longer maintained", "replacement_slug": "puppetlabs-mysql"} }' \ -H 'Content-Type: application/json' -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>' ~~~

## Bonus: Updated docs! Once we got into the documentation phase for these new endpoints, we realized our Forge API docs could use a little love. So another improvement we made along the way was to update our docs framework. Beyond just a fresh coat of paint, the new docs are clearer and easier to navigate, with added descriptions for a handful of parameters that hadn’t previously surfaced from implementation to the docs. (Screenshot of New Forge API docs)

Want to try it out? Log in to your Forge account, navigate to your user profile page (hint: click your name in the upper right), and on that page you'll see an option to create a new key. Once you've created a key, you're all set to hit the ground running with automating your module management.