JSON-LD + Hydra for a simple API-description

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 16:31:14 UTC