Simplify contract's specification

[jmmercadom]

The specification (of a contract) right now is very verbose. For anything non-trivial, the specification is basically non-human readable. We could use the yaml representation of json-schema as that is more compact and then write a simple DSL that represents the request-response bits and keep the structure of the actual response body still in yaml representation of json schema.

[maxlinc]

:-1

doing a yaml representation of json-schema seems silly. i'm also hoping the format will stay pretty portable. json-schema is supported by multiple programming languages.

i think a more worthwhile enhancement would be something to help generate contracts from sample data. check out https://github.com/perenecabuto/json_schema_generator/blob/master/USAGE.md for some inspiration

[marcosccm]

We are beginning to use Pacto on our current project and we got to the same conclusion, writing json schemas by hand is a big pain and it seems to be easy to generate the schema from a sample.

Lots of apis have samples of their return json somewhere on their documentation, so using plain json can help a lot the initial adoption of contracts, and is also much easier to read =) Going to implement that soon.

[maxlinc]

Take a look at http://apiblueprint.org/

[tmattia]

A friend just pointed me to http://orderly-json.org/docs. On a first glance it looks very promising, although is has not been maintained for quite a while. I haven't really looked in detail yet, but thought it would be worth sharing. Thoughts?

[tmattia]

Another really nice approach to the same problem (note that they're using YAML): https://github.com/square/fdoc

[maxlinc]

I'm not sure why I said YAML was silly. The only thing I can think is - if it's just an alternate format for the same schema, then 👍. If it's a different schema, then 👎.

I'll assume it's just support for loading the same schema. This has some benefits and is pretty easy to implement. Benefits:

• It's a bit easier to read (at least some people feel it is)
• It allows comments. Not only may this be useful to users, it also lets us write documentation with docco or groc. I had been .js instead of .json files as a documentation workaround.

There are some additional changes I'd proposed, but I suggest closing this issue once YAML support is added, and creating a new issue for "Proposal: Contract Format 2.0" issue.

[maxlinc]

Another format to check out. It's "heavily inspired by Swagger", not sure what the differences are from Swagger as json.

http://guzzle.readthedocs.org/en/latest/webservice-client/guzzle-service-descriptions.html

A lot of it looks pretty interesting, but some things are more complex than I'd want to support (initially).

[maxlinc]

I'm going to go with Swagger 2.0. The current Swagger was pretty close to what I wanted, but I was worried it wouldn't quite address my needs. Now there's an active working group for Swagger 2.0 which is trying to make Swagger even better. I've joined the working group but haven't made any contributions yet.

The reasons I feel Swagger is the right choice:

• Swagger is very popular. It "estimated to have around 10,000 deployments in production" and the "Java client alone has been downloaded over 500k times"
• I like their stated goals for the next generation of swagger, especially "API design-first workflow" ("human-friendly YAML syntax and editor") and "Best-of-breed tooling"
• Swagger is probably the most popular API definition right now, and hopefully Swagger 2 will make it even better and more popular
• Swagger is much more human readable and parsable than WADL
• Swagger is more parseable:
  • apiblueprint (which requires a Markdown parser though it can be can be converted to json or yaml)
  • RAML (which requires YAML parsing extensions)

Now, we won't be able to switch to swagger overnight. My plan is simply to start making Pacto more swagger-esque, with the eventual goal of Swagger compatibility.

Any objections?

[maxlinc]

FYI - samples and schemas for Swagger 2.0 are at:
https://github.com/reverb/swagger-spec

[maxlinc]

If I haven't sold you yet, read this:
https://blog.apigee.com/detail/a_design_first_approach_to_building_apis_with_swagger