Propose changes to format allowing greater flexibility.

[alexcouper]

Continuation of part of the discussion from apibyexample/abe-python#11.

This may not be the direction the spec wants to go in, and if not then that is absolutely fine.

Proposal

That the spec be more flexible in allowing different use cases whilst still maintaining backwards compatibility with existing workflows.

What is being changed.

Currently:

Each json spec file is meant to declare "one API call". This means that all examples in the file should use the same method and path - the only changes should be to request bodies.

Removing some strictness:

Each example in a spec file can override the path. I believe the idea is that this is only for expansion of eg. regexes of a path at the top. Currently at least in abe-python this isn't inforced (ie if an example in the spec defines some completely different path there will be no errors)

I think this is a good thing in that it allows the user to have more control over what they want to illustrate with an ABE file.

I'd like to go one further and have the spec explicitly support overriding of both path and method in the spec to allow people to use it in different ways:

• Show/Test a single request with different values
• Show/Test all the CRUD operations against a single resource

They could use it to show the full set of GET requests available across all resources.

Example

I've made a change to the Readme in order to hopefully illustrate what I mean.

[alexcouper]

@txels @nwhite89 any thoughts on this?

[nwhite89]

Theoretically I guess you could do this already with the current structure it's more that the testing systems won't?

I'm not against it does mean it's a file about a whole API rather than an end-point, @txels / @alexcouper what do you think about the flexibility for both ways? I wouldn't want to go away from what we have at the moment as with upcoming new API's such as OpenGraph I would imagine ABE wouldn't be used in this way as the API generally depends on your Request and it's the API as a whole isn't necessarily "spec'd" out other than what you can request.