For Contributors

Work on API Atlas will hit production and impact real developers within weeks. We have a growing list of developer tools including Optic, Readme and Sourcegraph that are currently using insights from API Atlas or are working to integrate them soon.

If you want to help out, there are a few ways to get involved:

  • Writing Optic Skills for a particular API Framework
  • Adding Language Parsers to Optic
  • Ideas + Feedback

Writing Optic Skills for a particular API Framework

They syntax of each API framework is unique, but they are all map to our shared understanding of an API. Our goal is create a parser for each API framework that can document the API in a machine-readable format.

alt text

We can easily create these parsers by writing Optic skills. Here’s an example of the Optic Skill for express-js.

Optic uses its models of different programming languages to help you automatically create these parser. All you have to do is provide it with example code and the expected output. It then creates a regex-like parser that walks over the AST tree and extracts information about a certain kind of code.

This is the code you need to teach Optic how to recognize parameters from express:

const parameters = js`req.query.paramName`
.abstractionSchema('apiatlas:express/parameter')
.abstraction({
	in: tokenWithValue('query'),
	name: tokenWithValue('paramName')
})

These smaller parsers can be assembled into larger parsers for the entire endpoint:

export const route = js`
app.get('url', (req, res) => {
	//:handler
})`
.abstractionSchema('apiatlas:express/endpoint')
.abstraction({
	method: tokenWithValue('get'),
	url: literalWithValue('url'),
	parameters: collectUnique('apiatlas:express/parameeter'),
	headers: collectUnique('apiatlas:express/header'),
})

Adding Language Parsers to Optic

In order to support a new programming language we need to include an off-the-shelf parser for it within Optic. We’re writing a tutorial explaining how to do this now (stay tuned). In the meantime here are some examples:

Ideas + Feedback

The contributions of ideas + feedback are often overlooked by the open-source community even though these are often more valuable than lines-of-code. As the project grows there will be many interesting opportunities and challenges that arise. If you want to join our Slack, participate in planning/design, talk about our big ideas, and provide feedback along the way we’d love to have you.