Re: On building web service clients for specific tasks

I've simplified the API documentation even more and I think now it
should be almost finished.

I'd appreciate a lot some help if possible. Because of that I've
narrowed down my questions to the most important. The rest I've figured
it out by myself or I don't care at the moment.

- I have a link pointing to a Collection of cities. I also have a City
  Class. Is it necessary to declare the Collection Class as in the
  documentation of the Issue Tracker example?

- The City entity has embedded data about the tomorrow forecast. I
  don't know if I've done it right.

- Same with the search interface that I've defined in the EntryPoint.
  It doesn't specify what it returns. Maybe it's necessary the
  "supportedOperation" array.


Thanks!



El Wed, 19 Aug 2015 00:46:28 +0200
Miguel Casal <dev@miguelcasal.net> escribió:

> El Mon, 10 Aug 2015 21:51:45 +0200
> "Markus Lanthaler" <markus.lanthaler@gmx.net> escribió:
> 
> > In general, I'd try to use the Hydra ApiDocumentation as much as
> > possible. It can give you lots of hints depending on how well the
> > service is described. So, in the example you outlined above, you'd
> > try to find a User object whose name property has a specific name.
> > There would be multiple ways to achieve that (not all are supported
> > by the demo issue tracker):
> 
> 
> I've been trying to define the API documentation for a fictional
> forecast web service using the Hydra demo as a guide. So far this [1]
> is what I got.
> 
> I have a series of comments, doubts and problems I'd like to expose to
> you.
> 
> 
> Comments
> --------
> - It would be useful to mark one specific vocabulary as default to
>   reduce the verbosity of the @context. So, if one attribute is not
>   qualified by a namespace, search its definition in the default one.
>   I'm almost sure that JSON-LD has this very feature hehe
> 
> 
> Doubts
> ------
> - Do I have to explicitly define a generic collection with members if
>   it's the case of having one?
> 
> - What's the point of /required/ if the resource is going to be
>   retrieved but not created or updated?
> 
> - Aren't /readonly/ and /writeonly/ mutually exclusive?
> 
> - I'm trying to define embedded data (tomorrow forecast along with the
>   city representation) but I don't know if I'm even close of getting
> it
> 
> - What's the difference between the /label/ and /description/ inside
>   the property and /hydra:title/ or /hydra:description/?
> 
> - Is it mandatory a /domain/ in a property? What if it's going to be
>   used inside several representations?
> 
> 
> Problems
> --------
> - Use an appropriate type and range for temperature data [2]
> 
> 
> Many thanks and apologize me for the amount of doubts. As you guessed
> it, all this is new for me ;)
> 
> 
> [1] https://gist.github.com/miquecg/b8d479256aa24954c4fd
> [2] http://www.qudt.org/
> 
> --
> Miguel
>

Received on Wednesday, 26 August 2015 20:12:10 UTC