Skills SDK

This weeks marks the end of Optic’s YC Batch. Working with the YC Partners, alumni and PG himself was an amazing experience and I think both myself and Optic are in a far better position than when the summer started. Optic’s team is still just me, but there is now a much wider cast of supporting players contributing their time, code and ideas on regular basis. Thank you to everyone writing emails each week about your thoughts on Optic and for those of you who answer my texts asking your opinions on different ideas at the oddest of hours.

Over the summer we’ve seen our daily usage grow and we’ve had the opportunity to work with a handful of larger development teams that want to use Optic. There’s still a lot of work to do to make Optic useful to a broader range of developers, but we finally have a good idea of what those things are and we’re excited to start building. Now that YC is over we plan to hire 2 full time engineers that can help us take Optic to the next level. If you’re interested in being one of them or know who we should talk with please email me at aidan@useoptic.com

Goodbye Optic Markdown

This week we’ll be sunsetting Optic Markdown, our attempt to make documentation human + machine readable by adding annotations above example code. In general I still believe documentation will one day be usable by both humans + machines, but looking back I think this is an area in Optic’s architecture where I was perhaps too bold. Here are some reasons we’ve decided to move away from this approach:

  • difficult to learn - every dsl we came up with (and we went through 2-3 iterations) had a pretty steep learning curve.
  • intimidating - users thought they had to write nice docs alongside our annotations
  • hard to test - since md isn’t really suited for writing tests the only way to see how your skills would behave was loading them up in Optic
  • doing both poorly - if all the other reasons were not enough, our annotations made great docs look bad

Hello Skills SDK

In response to this feedback we’ve begun working on the Optic Skills SDK. Our design for the Skills SDK is focused on achieving a high degree of learnability and testability. Instead of unfamiliar annotations Optic skills will be created by calling functions that ship with the SDK.

To define a lens you provide example code, and an object describing this code as data:

const lens = js`
app.get('url', (req, res) => {
	//:handler
})`

lens.value = {
	method: tokenWithValue('get'),
	url: literalWithValue('url'),
	parameters: collect(parametersLens),
	headers: collect(headerLens),
	responses: collect(responseLens)
}

lens.containers.handler = AnyChildren

To define a schema:

Schema('example', {
	type: 'object',
	properties: {
		value1: {type: 'string'},
		value2: {type: 'string'},
	}
})

And finally transformations are described by writing actual functions:

Transformation('Name', 'input:schema', 'output:schema', (input, answers) => {
	return {key1: input.a, key2: input.b}
})

The Skills SDK will also ship with test scripts that make it easy to simulate generating, parsing and mutating code throughout your project:

it('can generate express parameters', (done) => {
    packageTestKit.testLens('express-parameter', (lensTestKit) => {
        const result = lensTestKit.generate({in: 'query', name: 'abc'})
        assert(result.success)
        assert(result.code === 'req.query.abc')
        done()
    })
})

When you're ready to use your skills you'll be able to run opticsdk publishlocal to try it out locally or opticsdk publish to deploy it on our public registry of skills.

Our goal for the SDK is to make it easy for anyone to learn, build and share useful Optic Skills in minutes, not hours.

Status

We plan to finish our first release of the Skills SDK over the next week. You can follow our progress here on GitHub. If you have any ideas for how to make the SDK great please share them with me at aidan@useoptic.com

Once the SDK is finished I'll a) be porting all the current Skills to the new SDK so there are an abundance of examples to reference and b) start a wholesale rewrite of all the Optic docs.

Future of the SDK

The SDK, if it's successful, provides the ideal staging area for more sophisticated tooling within Optic. Many Optic users at larger companies are interested in using Optic for high level linting. A traditional linter will only help you catch syntax errors and they require extensive knowledge of the AST tree to write. Optic, with its higher level understanding of your code, opens the door to much more powerful linting rules created with a fraction of the work.

For instance, if you wanted to check that all post endpoints had authentication you could write a rule like this:

Rule('optic:rest/endpoint', (endpoint) => {
  return endpoint.method === 'post' && !endpoint.auth
}, 'All post endpoints must have authentication')

This idea of advanced Optic linters is still very nascent, but we imagine it fitting very nicely into the SDK.

Thanks for your support and please check out the SDK when it launches!