notes-apicraft-describing-apis.md

Describing APIs

• Idea is to have a DSL/structured file that will describe your API

• Question: is there a repo where people share their Blueprint schemas so we can see them?

  • Not right now. There are definitely plans to make it really open
  • Some people are already sharing their blueprints on GH

• There are no other ways to collaborate on API design

• Describing, designing, documenting APIs

  • Idea is to have a workflow integrating Blueprint with development
  • Push new revision of the spec, have tests run? Another session re API testing is scheduled for 3pm.
  • Curl trace parser:
    • curl --trace generates a trace file
    • Apiary wrote a tool to parse that file and output the request in Blueprint format
    • This output can then be used with Apiary so you get documentation, a stub service, etc.

• Suggestion: document a famous/real-world API with Blueprint

  • They're doing this with App.net's API

• Markdown itself is not a very consistent format. Different flavors, different parsers, etc.

  • Apiary's Markdown is compatible with Github's

• Question: how to keep the actual API implementation in sync with the specification?

  • Tests: the API spec is a test.
  • There are some projects integrating Blueprint with the actual code (someone hooked it up with Rails)
  • Seems like there's not best practice, though. First design and review it, then implement

• There's also an idea to take the curl parser and move it to the server side (eg: a proxy that documents the requests using that same format)

• Question: is this sufficient to document actual APIs?

  • With JSON Schema developers can use a different format to specify data types, etc
  • There's also support for URI templates

• With statically typed languages it's obviously easier to test/be explicit about types. Dynamic languages need another layer/more explicitly check for it.

• Future development on Blueprint

  • Better support for links
  • More DRY
  • Multiple files
  • What about curl examples for the docs?
  • What about authorization?

• Human readable makes sense, but it's nice to have Swagger closing the gap

  • Concerns re spec drifting from actual implementation
    • Blueprint is about documenting and testing
    • Apiary built tools on top of Blueprint
    • Users are working on their own tooling
    • Blueprint is open source, users can share their tools/ideas for it
    • One could convert from Blueprint to Swagger, etc
  • This is just part of the documentation?
    • Markdown helps, when you write API endpoints Blueprint will kick in, but arbitrary content is still supported, etc.

• Is it possible to embed Blueprint in a block of comment that goes together with the code?

  • No official tooling for this today. But it's certainly possible to scrap these out of the code and merge into a Blueprint (markdown) file.
  • This new Blueprint format just came out yesterday. Still a lot to be discussed, etc.