Feedback

[smizell]

Hey Mike!

I hope it's OK to provide a little feedback on this. I really love that you're
exploring this idea, especially in the way you're exploring it. For one, I
recently built a hypermedia API and struggled with existing formats to describe
what I wanted to describe, and this would have been helpful during design. Two,
I spent some time myself thinking about a multiple-use format when tinkering
with Verbose.

Actions

1. While you use actions, I see that you also call it a "transition"
   throughout the actions sections of the spec. Might be nice to sync these up?
2. Having an action property on an action object felt a little strange to
   me.
3. I commonly use a transition type that does not fit any of the actions you've
   listed there. I use "POST" for a kind of processing action, like to mark a
   todo item complete or toggle something. I've called this kind of transition
   just a "process" transition when I've worked with it, though you can probably
   think of a much better name :)
4. Is safe/unsafe implied by the action property? Are you wanting to allow for
   things like read to be unsafe? If it's implied, you may be able to
   simplify.
5. You could make target and array rather than a space-separated string.
6. I know rel is a very well-known term, however there are two things here I
   wanted to mention. One, it's maybe the only property in the spec that is an
   array and not pluralized. Second, there is a slight name collision with
   related in the wstl object.
7. Thinking out loud, but if you change prompt to title, you could use this
   pattern throughout your objects, giving each a title and description.
   However, prompt does give more meaning than the simple title.

Input Objects

1. You have basically three states for readOnly and required. What should
   libraries do when these are absent? Do you want a default?
2. Similar idea with type. Do you want a text value that is the default if
   not listed?

Data

I have curiosity about the data property as it doesn't get a lot of discussion
in the spec. It looks like it can be any kind of array of objects. How would
someone specify the semantics and structures used for data? Would this be done
in an ALPS document?

Personally, I have found this to be one of the hardest parts to get right in
defining a generic structure and a way to define semantics for that structure.
There is a balance between defining semantics apart from structure, but doing so
in such a way that they can be matched easily to properties in the structure.

In Verbose, this lead me to defining a semantics section that was flat, with a
properties section that could be deeply nested. I'm not sure I found the balance
myself, but I do think it's an interesting area to think through.

Closing Thoughts

In some recent work of mine, I found that I really needed the ability during the
design phase to define when an affordance (i.e. action or transition) would show
up in a response. Resource Blueprint goes the direction of defining conditions
on a given affordance, but I ended up going a different direction recently of
defining scenarios and the expected affordances in those scenarios. I then used
those scenarios as a kind of unit test to ensure the right affordances showed up
at the right time. However, putting conditions on affordances may be better for
covering more area, so I'm still thinking through that.

I only mention that because that was the biggest thing I used during design time
of an API I just built, but I find it missing in many formats. Maybe it's a
problem you are interested in tackling in WeSTL, though I understand it may go
too far.

Hope all is well!

[mamund]

@smizell

wow -- this is great stuff.

i will add some responses here and we can expand on this in other threads.

Actions:

• yes, some of this can be consolidated/sharpened. i like the ideas you have here
  Inputs:
• hmm, defaults SHOULD be identified. i can add that ASAP.
  Data:
• you hit on a very important weakness in this design. and it is certainly a tough one. i "punted" on this iteration since i didn't know exactly how to solve this problem. but it needs attention. i think MSON might point to some possible solution here. maybe (even more to the point) RDF-style triples. i want to focus on this one to make it possible to build general translations from one model to another (i think you worked on this, too, right?)

Finally:
i crafted WeSTL to solve a narrow problem in my RWCBook. when i designed it, i knew it would need more more -- that's why i used the "prs" facet for the media type identifier. I'd like to take this design to the "next level" and that means changing the identifier to "vnd" (for the working version) and, eventually -- if it takes off -- to a full-fledged RFC-defined type.

I'd really like to work with you on this. my initial plan is to clean up the elements you mention here (on actions and inputs) in the "prs" edition and then (as soon as possible) fork this into a new repo for the "vnd" edition. there we'll have the freedom to create breaking changes needed to improve the overall design including a solid approach to modeling the data.

sound like something you'd be interested in helping me with?

[smizell]

Yeah, I'd definitely love to help! Should be fun. :)

Regarding data modeling, you can find the structure we used for MSON for defining the format as the Refract project. It is at the core a conceptual model for representing data structures, and functions as a sort of parse result for MSON, along with API Blueprint and Swagger. This is done by adding a semantic layer on top of Refract that we called API Elements. This allowed us to have a single AST for both formats and support both formats in all the tooling.

While we used a direct serialization of Refract, we also came up with a couple extra serializations. One is a compact form that resembles XML/Lisp. Another serialization format is what I called Embedded Refract that allows you to sprinkle in metadata into existing JSON structures. You may actually be interested in ideas around the embedded format as it allows for plain JSON that can be annotated when needed.

Another area you may be interested in regarding Refract is how we use meta links and profiles. We used them in our parsers in a similar fashion to RDF. Instead of being transitions, we used them to define data and provide helpful links for parse results (i.e. instead of telling users a cryptic code, we told them a URL that provided more info).

Lastly, to change gears a bit, I believe we are very close to having what you need in its entirety in API Elements. A couple of weeks ago, I opened up a proposal to add the ability to describe affordances in API Elements, which would lay a foundation for hypermedia support for API Blueprint and Swagger/OpenAPI if they were interested in exploring that. It would allow for MSON and affordance definitions to live side by side and be used at both design time and runtime, which is the basic idea of what you have here.

To note, I'm not at all suggesting here that you quit this work, but I do think it would a very interesting concept to consider API Elements as the AST for WeSTL. That's just a thought, but it may open you up to a world of existing tooling. For instance, we actually had a tool that used API Blueprint at both design and runtime called Hyperdrive.

To my last point, just to summarize, WeSTL could be a format that can be parsed into API Elements rather than using WeSTL directly. We've already done a lot of unifying work there, and maybe there is something for you to benefit. And personally I've really wanted to see a simple YAML or JSON format for writing API Elements, which was part of my thinking around the blog post I just did.

Just some extra thoughts! Looking forward to where this goes.

[mamund]

@smizell

OK, i've updated the current spec (prs.wstl+json) to fix the INPUT items you mention. The others are breaking changes and I want to handle those in a new fork or repo, depending on how we approach this.

I'll write an email directly to deal w/ MSON, API Elements, and other good ideas you mention here.

cheers.

[smizell]

Sounds great :) Feel free to close this issue if you like.

[mamund]

@smizell 👍
OK, closing this issue. we can pick this up via email and then start a new thread (or two).