search

thoughtworks / pacto

Pacto settles disputes between JSON providers and consumers
thoughtworks.github.io/pacto
MIT License
401 stars 58 forks source link

Simplify contract's specification #2

Open jmmercadom opened 11 years ago

jmmercadom commented 11 years ago

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 commented 11 years ago

:-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 commented 11 years ago

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 commented 10 years ago

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

tmattia commented 10 years ago

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 commented 10 years ago

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

maxlinc commented 10 years ago

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 :+1:. If it's a different schema, then :-1:.

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

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 commented 10 years ago

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 commented 10 years ago

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:

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 commented 10 years ago

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

maxlinc commented 10 years ago

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