Re: JSON-LD + Hydra for a simple API-description

Hi Jean-Gert,

apparently you want to start with an entry resource which allows to search 
for offered products by productID.

I would propose to make Strato the entry resource which has a collection of 
related offers:

{
"@context": {
 "@vocab":"http://schema.org/"
 "hydra": ...,
 "hydra:property":{"@type":"@vocab" }
},
"@type": "Corporation",
"@id": "https://strato.de/corporation",
"url":"http://www.strato.de",
"hydra:collection": {
  "@type": "hydra:Collection",
  "hydra:manages": {
    "hydra:property": "makesOffer",
    "hydra:subject": {"@id":"http://www.strato.de/corporation"}
   }
   "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "https://strato.de/buy/ger/offers{?productID*}",
    " hydra:mappings": [
      {
      "hydra:variable": "productID",
      "hydra: property": "productID",
      "hydra: required": true
      }
  }
 }
}

Ideally the @id of the Corporation is the URL where you can retrieve that 
resource, so I changed the @id to http://strato.de/corporation and added 
the url property for the www.strato.de address.
In your uri template you used the query continuation with &, that has to be 
? since you have no leading query before the &.

The reply to the query would again be a Collection, only this time with a 
hydra:member attribute that holds a list of Offer objects. The makesOffer 
belongs into the manages block.

{
...
"@type": "hydra:Collection",
  "hydra:manages": {
    "hydra:property": "makesOffer",
    "hydra:subject": {"@id":"http://www.strato.de/corporation"}
   }
   "hydra:member": [
     {
       "@type": "Offer",
       "@id": "http://strato.de/offers/whatever",
       "itemOffered": {
         "@type": "pto:Dedicated_hosting_service",
         "@id": "http://strato.de/konf_url_zur_aktn_konf_do_not_use",
         "productID": "SOL_K38_24"
         "name": "Server Hardware, 24 Monate Vertragslaufzeit",
       },
       "price": 3.20,
       ...
     },
     ... more offers matching the query ...
   ]
}
Otherwise you are all set. Heretic question: What is it you think you have 
to put into the ApiDocumentation which is not already in the response?

:)

Best regards,
Dietrich


Am 24. März 2015 17:31:54 schrieb Jean-Gert Nesselbosch 
<nesselbosch@strato-rz.de>:

>
> hello all,
>
> I'm quite sure, that this is a newbie-question answered somewhere
> else. so please be so kind to just point me to the approriate thread
> in this ng.
>
> anyway, here's the question.
>
> I'm trying to describe a simple API for the web-ordering-process of
> the company I'm working for. It's part of a much larger context. All
> the API has to do is receive some productIDs and return an appropriate
> offer, containing price-information concerning the requested productIDs.
>
> Here's what I've assembled so far :
>
> (1.a) request , formal spec
>
> {
>   "@context": {
>        "@vocab": "http://www.w3.org/ns/hydra/context.jsonld",
>        "sch" : "http://schema.org/"
>   },
>
>   "@type": "IriTemplate",
>   "template": "https://strato.de/buy/ger/offers{&productID*}",
>   "mappings": [
>     {
>       "@type": "IriTemplateMapping",
>       "variable": "productID",
>       "property": "sch:productID",
>       "required": true
>     }
>   ]
> }
>
> (1.b) request , example :
>
> https://strato.de/buy/ger/offers?productID=SOME_PROD_ID_1&productID=SOME_PROD_ID_2&productID=SOME_PROD_ID_3
>
>
> (2.a) the intended reply (draft, example) ###
>
> {
>    "@context": {
>      "@vocab": "http://schema.org/",
>      "pto": "http://www.productontology.org/doc/"
>    },
>
>    "makesOffer": [
>      {
>        "@type": "Offer",
>        "@id": "http://strato.de/offers/whatever",
>        "itemOffered": {
>          "@type": "pto:Dedicated_hosting_service",
>          "@id": "http://strato.de/konf_url_zur_aktn_konf_do_not_use",
>          "productID": "SOL_K38_24"
>          "name": "Server Hardware, 24 Monate Vertragslaufzeit",
>        },
>        "price": 3.20,                      // im 1. Abrechnungszeitraum
>
>        "alternatePrice" : 4.20             // preis des teuersten
>                                            // alternativen Artikels
>        "savings" : 80,                     // ersparnis
>        "savingsUnit" : "%",                // ... in prozent
>        "billingPeriod"     : 3,            // abrechnungszeitraum
>        "billingPeriodUnit"    : "Monat"    // ... in monaten
>        "priceCurrency": "EUR",
>        "description" : "Sie sparen 80 %.", // weitere infos,ggf.red.
>        "language" : "ger",
>      }
>    ]
> }
>
> now here are my two questions :
>
> (A) how do I turn the example-structure from (2.a) into the appropriate
> matching part of the intended API-reply-description (must be something
> to do with the keyword "returns" since it should describe the structure
> of the returned API-reply)
>
> (B) how do I assemble the API-description of the request (1.a) and the
> API-description of the reply (see (A)) into a comprehensive description
> of the intended API.
>
> also, the description should contain some information about the company
> providing the api, that is, e.g.
>
>   "@type": "Corporation",
>    "@id": "http://www.strato.de",
>    "name": "STRATO AG",
>
> where do I put this information ?
>
> kind of confused,
>
> jean-gert nesselbosch
> STRATO AG,
> Berlin, Germany
>
>

Received on Tuesday, 24 March 2015 22:05:22 UTC