Re: an architectural diagram

Hi Markus,

> It's a great first step but not detailed enough.

Exactly, but good enough to start a discussion,
which was the whole point :-)
Once we agree on the first level, we go to the next.
No point in working on details when the big lines aren't agreed upon.

So thanks for these questions,
those were exactly what I was looking for.

> - I think "Forms" isn't such a great name as it implies a 
>   visual representation IMO

It doesn't to me; what do other think?
A "form" is a structured way of inputting things
(think about paper forms etc.).

> - I'd suggest to categorize hypermedia controls into safe vs. unsafe
>   (or similar terms) instead of Read vs. Write/Update/Delete.

Perfect; changed.

> - Not sure if the division into "Hypermedia Controls" and "API Modeling"
>   is the right one..

Another argument for the current level of detail ;-)

> I personally would put Fields under API Modeling..

Aren't we talking about properties then?
(And isn't that kind of modeling done with RDFS/OWL?)

>   I understand you mean the description of variables/placeholders of a
>   URI template

Not only a template, also an HTTP body (such as POST).
Fields is about the serialization or properties.

> but the diagram doesn't make this clear

Some definitions below could definitely help;
part of this exercise is to find them.

> why does Paging depend on URI Templates?

For jumping to specific pages,
but not for next, prev, first, last indeed.

> Why Resources on Errors?

Maybe first a general interpretation remark:
the names are names for packages, not classes.
So the “Resources” package can contains things like
resource types, instead of individual resources.

I was thinking that we might want to describe
which types of errors occur with which resources.
However, looking at the examples in the current spec,
it seems that the errors are attached to the API.
So perhaps “API Modeling” needs an additional
“API” class that represents the entire interface?

Best,

Ruben

Received on Wednesday, 4 January 2017 22:56:55 UTC