[Call for Feedback] API for Stoplight Next


(Taylor Barnett) #1

The Stoplight API is coming soon :tada:

I wanted to start a conversation about what tasks you would like to do via the Stoplight API that help integrate Stoplight into your workflow.

I have talked to some Stoplight users who have used it with Stoplight Classic (https://app.stoplight.io) and are looking forward to it in Stoplight Next (https://next.stoplight.io).

What tasks would you like to do via the API? We will be taking these into consideration as we expose different API endpoints.

For example: You would like to upload your specification file to Stoplight via the API.

(Marc) #2

Step by step examples of desired workflows would be very helpful!

Some relevant API endpoints that might help build up various workflows:

File Management

For working with the files in your Stoplight projects.

  • files.get
  • files.create
  • files.update
  • files.delete


  • domains.create
  • domains.update
  • domains.build (with an optional set live param to also “publish”)
  • domains.delete

… whatever else you guys can think of.

(Joe Mcilvain) #3

I’m part of a team that is using Stoplight in a hands-off, automated way (not using the Stoplight UI nearly at all), to construct and publish documentation after pulling in data from various repositories and sources in our project. We’re in the process of trying to close remaining gaps of migrating to Stoplight Next to do a similar workflow there.

Taylor has already showed me how to push our docs directly to the Stoplight Next git repo, and our script for doing this already works beautifully.

The only remaining gap we have is being able to trigger an update to the published documentation to point to the information from the latest commit in the git repo that we pushed to.

As such, closing this gap would be my highest priority feedback for Stoplight Next, so that we can publish programmatically, ferret out any remaining QA issues with our build scripts and data sources, then complete the migration.

(Marc) #4

Thanks for the good feedback Joe - for triggering an update do you need an option to do it for a specific commit hash or would it work if it just pulls from the latest on master?

(Joe Mcilvain) #5

Pulling from latest master would be sufficient for our purposes.

(Nicolas Tisserand) #6


We are (soon) using Stoplight Next on Premise with SAML authentication.
The SAML assertion only checks the login, not the user rights.

It would be useful to have an API to manage the users, organizations and roles in the orgs.
With such an API, we could update user rights every night by batch. (This implies that there is a superadmin user or something similar)

  • Organization : list, get, create, update. (Not delete, too dangerous : what would happen to the projects inside ?)
  • User : list, get, create, update. (Not delete, but keep the possibility to disable by UPDATE)
  • Roles : only list and get (the roles are built-in, so no operation to alter them)

In the user API :

  • provide a feature to assign (or remove) a specific role for a user into an organization.
  • retrieve the date of last login in the resource
  • don’t show the tokens created by users in “Account Settings > Access Tokens”

(Thomas De Groof) #7

@taylor do you have any timeline for the Stoplight Next API?

We have tooling that generates code from Swagger, would be great if we could import OAS files from Stoplight using the API.

(Taylor Barnett) #8

Right now, we are targetted to release part of the new API in the next Stoplight release, which would happen in a few weeks. There’s a stretch goal in there that includes the endpoints that allow importing OAS files into Stoplight.

(Erik Hansen) #9

@thomas.degroof, while you wait for the API support, you can support your workflow through Git https://docs.stoplight.io/platform/projects/git-repo

(Taylor Barnett) #10

Yes! Thanks for sharing that. I wrote the docs for it.

(Thomas De Groof) #11

@erik.hansen thanks for sharing that doc! #TIL