Kudos. And a half-baked idea for an application.

[ariutta]

Kudos on your work! I'll be watching to see where it goes.

The half-baked idea I'd like to work on sometime (when I get time):
Up till now, hypermedia APIs have not gotten as much as attention as they deserve, arguably because they are designed for a theoretical client that doesn't actually exist. What if this client did exist in the form of code completion and validation engines for multiple languages? By existing only as a helper for the developer, it might avoid the mess of CORBA and SOAP.

Hug could make this easy if it used the HTTP Link Header to return type information. For example, it could return the following for the /users API endpoint:

{
  "@context": "http://schema.org/",
  "@type": "Person",
  "@typedef": "http://www.janedoe.com/typedefs/person.d.ts"
}

With http://www.janedoe.com/typedefs/person.d.ts being something like this (using Typescript to describe JSON because JSON Schema is unwieldy):

interface Person
{
    name: string;
    jobTitle?: string;
    telephone?: string;
    url?: string;
}

And a sample response body for a GET request:

{
  "name": "Jane Doe",
  "jobTitle": "Professor",
  "telephone": "(425) 123-4567",
  "url": "http://www.janedoe.com"
}

Related:

• Hydra: Hypermedia-Driven Web APIs
• Code generation

[timothycrosley]

HI @ariutta, I think this is an interesting idea and would be interested to see what would come by exploring it further. Potentially including it as a plug-in for hug?

Thanks!

~Timothy

[ariutta]

Yes, a plug-in sounds like the right place for it. I'm a little tied up with other projects right now, so it'll be awhile before I can get to it :( But I'd love to find out whether something along these lines would get traction in the dev community.

Any opinions on the best format for the type data? JSON Schema might be easiest to apply for multiple languages, but it's really verbose. Typescript is nicer to work with, but it's geared toward JavaScript, and each language would need a parser for TypeScript type definitions. JavaDoc (JSDoc/PythonDoc/etc.) style documentation comments are another option, although they are intended more for their target languages than for JSON.

[Mec-iS]

@ariutta I had a quite similar idea, see #34 (not involving TypeScript)
It would be great if the user could set a flag in the config file like HYDRA = True beside an handler for the api doc: the library this way could generate a basic ApiDocumentation file and automatically add the LINK to the vocabulary in the Response Header with the proper rel.

I have never developed on third party library, but with the right hints I could implement the thing. I am a Python developer and I have quite good knowledge about REST and HYDRA.
Let's talk about.
Cheers!

[ariutta]

Hi @Mec-iS, you're right - we're thinking along the same lines. Versions of these ideas seem to be popping up all over.

As a matter of fact, check out what the FB GraphQL team just released: a GraphQL IDE explorer with "typeahead query completion, error highlighting, query results".

Netflix is using Falcor with Sentinel metadata for API typing and cache invalidation. See also: https://speakerdeck.com/btholt/falcorjs-and-react

BreezeJS works with OData for API typing, although the NuGet team actually moved from OData to JSON-LD.

GraphQL is moving away from strict REST/Hypermedia patterns more than BreezeJS/OData, which makes it less useful for public APIs and especially for Linked Open Data. Not 100% sure about Falcor for that case. What about one of these options:

1. Create a server based on hug that could work with BreezeJS, but instead of relying on OData, create a replacement based on JSON-LD/Hydra and TypeScript (or possibly JSON Graph)? That would involve building on hug to create a server that could return JSON-LD with TypeScript interfaces as typedefs. Then for JavaScript purposes, the JSON-LD @context and TypeScript interfaces could be used to generate metadata, as described here: http://breeze.github.io/doc-js/metadata-by-hand-details.html

2. Create a Falcor server based on hug, possibly using JSON-LD/Hydra instead of JSON Graph

BTW, @timothycrosley, do you think this thread belongs here or in its own repo?

[Mec-iS]

Hi @ariutta
I think h.u.g. (as any good server, or server-level layer) should be completely independent from which client is going to hit it (the same for the output format on the other direction). So making the library compliant to any W3C standard out there is a good start (like the to-be standards HYDRA, and the Triple Pattern Fragments).

I am taking a look to all the options you pointed out; but they all seem to be supported by different actors in the market, without a defined standard to base on. So, talking server-side, I would base the first improvement on HYDRA. After that, the next step could be to leverage the HYDRA feature in h.u.g. to make the server able to respond to as many clients libraries on the market as possible.

So, much simpler:

1. Let h.u.g. users to easily create and use the HYDRA vocabulary via the ApiDocumentation (simply letting the user decorating a view for this purpose)
2. See how REST/HYDRA coupling and the needs of the different clients evolve

Your point 2. could be nice, but i don't see any advantage to port h.u.g. to Falcor. I think h.u.g. has a good potential as it is (Falcon is a very good web-server): adding support to other W3C standards (maybe also to SPARQL endpoints for LD, using a good triple store) can be a great way to go.

See you on the gitter chat for futher exchanges of ideas.
Cheers!

Links:

• an example of HYDRA ApiDocumentation

[ariutta]

Closing this issue, because this is probably more of a plugin, which would go in a separate repo.