Re: Top-down workflow

Am 17. Februar 2015 23:10:32 schrieb Marcos César de Oliveira 
<mcesarhm@gmail.com>:

> Hi, everyone.
>
> I'm a MSc student at University of Brasilia and a employee at Brazilian
> Ministry of Planning, Budget and Management.
>
> I joined this list recently. I'm experimenting with JSON-LD and Hydra to
> support a API redesign which I'm involved. I know that the preferred way to
> integrate Hydra with web services is to use tools like HydraBundle or
> hydra-java, but this is somewhat a bottom-up workflow, and, I think, not
> suitable for all use cases.

+1

>
> So, I reasoned if a top-down workflow, which starts with a API
> specification document, written using JSON-LD and the Hydra vocabulary has
> value. The advantages that I can see are: design an API without needing a
> implementation, to involve non-developers in the process of design,
> implement the same API in diverse programming languages.

and it allows teams to agree on the interface and start implementation of 
clients before the service becomes available, e.g. using mocks.

It also allows the server team to collect early feedback and adjust the 
interface iteratively. That would be my focus, beware of big upfront design 
and frozen interface contracts.

One challenge is that the Api evolves and the desire for roundtrip 
engineering will come up, which is a dark alley :)
I never found it appealing to redesign or refactor by means of a design 
tool. Once the code is there, it is more natural to work with the code.


>
> Accordingly, a tool set must exist to aid with this workflow. First, we
> could have a code generator tool to convert the API specification into the
> desired programming language. Also, we could have a tool to aid in writing
> the API itself.

But take note of the reasons why in the end we do not use UML to write 
code, but we use IDEs. Especially bad is a binary model format which cannot 
be edited simultaneously via version control. My idea of tool support would 
be an IDE plugin which helps me e.g. to get the linked data urls right, 
tells me about dangling or undefined attributes or inconsistencies, shows 
me the state machine of my application.

I guess one could use apt for java generation with immediate IDE and 
compiler feedback. Dagger2 uses that to give you a compile time warning for 
undefined bean injections.

>
> In that sense, I developed a simple prototype used as a proof of concept of
> the code generator. It is very crude, and works only for Java as target.
> But it can be used to experiment with these ideas. The source-code is
> available at https://github.com/mcesarhm/hydra2java.
>
> I would be very grateful in getting feedback of yours about this idea, and
> about the prototype.

Note to self: have a look at Marcos' prototype :)

>
> Thanks in advance,
>
> M.César