XML Partner-Schnittstelle

Der Zugriff auf die JPC-Artikel erfolgt über eine standardisierte Web-Schnittstelle. Der Zugriff erfolgt hierbei über einen GET oder POST-Request. Bei den Rückgabewerten handelt es sich um validierte XML-Dokumente.

Inhalt

  1. Abfragen
  2. Antworten
  3. Schema
  4. Beispiel-Programm
  5. Links
  6. Anhang

  1. Abfragen

    Die Abfragen erfolgen über GET/POST-Requests an den Webserver. Syntax der Abfrage:

    Base-URL
      baseurl = "http://www.jpc.de/jpcng/"
    bzw.:
      baseurl = "https://www.jpc.de/jpcng/"

    Es gibt zwei Möglichkeiten auf Artikeldaten zuzugreifen. Zum einen können Details eines Artikels direkt erfragt werden. Zum anderen können ganze Artikellisten über verschiedene Suchparameter abgefragt werden.

    Details eines einzelnen Artikel
    Zur Abfrage eines Artikels muss die URL folgenden Aufbau besitzen: 
      url = baseurl + "home/xml/-/task/detail/hnum/" + hnum
    Die hnum entspricht dabei der JPC-Artikelnummer, bzw. der ISBN-Nummer.
    Beispiele: 
      http://www.jpc.de/jpcng/home/xml/-/task/detail/hnum/3257228007
  http://www.jpc.de/jpcng/home/xml/-/task/detail/hnum/8391494
  http://www.jpc.de/jpcng/home/xml/-/task/detail/hnum/6891398
  http://www.jpc.de/jpcng/home/xml/-/task/detail/hnum/4001159

    Suchabfrage
    Es gibt verschiedene Möglichkeiten eine Suche über die JPC-Artikel durchzuführen. Der Grundaufbau der zu übergebenen URL hat dabei folgendes Muster: 
    	  url = baseurl + genre + "/xml/-/task/" + kategorie + begrenzung
    Bei allen Varianten ist die Umgebung anzugeben, in der die Suche durchgeführt werden soll. Dazu ist die Angabe des genre notwendig.
    Soll eine globale Suche durchgeführt werden, ist hier home zu setzen. Bei allen anderen genre-Typen wird die Suche auf die jeweilige JPC-Rubrik beschränkt.
    Genre Bedeutung des Elementes
    homeAlle Rubriken
    jazzJazz
    poprock Rock & Pop
    classicKlassik
    movieFilm
    booksBücher
    scoreNoten
    Gemeinsamkeiten
    Einige Begrenzungsparameter sind allen Suchabfragen gemeinsam. Mit diesen Parametern lassen sich die Suchabfragen auf Teilabfragen beschränken. So kann der Startpunkt und die Länge der Artikelliste angegeben werden. Ebenso kann die Suche auf ein bestimmtes Medium und auf eine Rubrik (falls dies nicht schon über genre geschehen ist, vgl. genre-Typen) beschränkt werden.
    Parameter BedeutungWertebereichDefault Wert
    searchcount Anzahl der Artikel(integer)25
    searchfirst Erster Artikel. Beginnend bei 0.(integer)0
    mediumArtikelmedium(string)all(*)
    rubricGenre
    (*)eine genaue Beschreibung finden Sie im Anhang
    Die Paramater werden über die begrenzung gesetzt. Dabei ist die Reihenfolge unwichtig. Wichtig ist, dass jeder Parameter dem Aufbau /param/value folgt.
    Beispiel: 
      http://www.jpc.de/jpcng/jazz/xml/-/task/charts/searchcount/42/searchfirst/13
    Die Standardsuche
    Für die Standardsuche wird die kategorie auf search gesetzt. Der zu suchende Begriff wird dabei über den Parameter fastsearch übergeben. Alle anderen Parameter gelten weiterhin.
    Parameter BedeutungWertebereichDefault Wert
    fastsearchSuchbegriffe (URL-encoded)(string)
    Beispiele: 
      http://www.jpc.de/jpcng/home/xml/-/task/search/fastsearch/unreal+tournament
  http://www.jpc.de/jpcng/movie/xml/-/task/search/fastsearch/david+bowie/medium/CD
    Die kategorie-spezifische Suche
    Bei der kategorie-spezifischen Suche wird keine Suche zu einem Begriff durchgeführt, stattdessen besteht die Möglichkeit fertige Listen abzufragen. Zu diesen Listen gehören die Angebots-, Neuheiten- und Hitparadenlisten der verschiedenen JPC-Rubriken.
    Kategorie Bedeutung des Elements
    offersAngebote
    novelties Neuheiten
    chartsHitparade
    Die Neuheitenliste läßt sich ausserdem noch zeitlich weiten. Standardmäßig werden die Neuheiten des aktuellen Tages ausgegeben. Folgende zusätzliche Angaben sind möglich.
    ParameterWerteBedeutung
    daycount(integer)Neuheiten der letzten x Tage
    future1zukünftige Neuheiten
    Beispiele: 
      http://www.jpc.de/jpcng/movie/xml/-/task/charts
  http://www.jpc.de/jpcng/poprock/xml/-/task/charts/searchcount/42
  http://www.jpc.de/jpcng/jazz/xml/-/task/charts/searchcount42/searchfirst/13
  http://www.jpc.de/jpcng/movie/xml/-/task/offers
    Die Profisuche
    Auch für die Profisuche wird kategorie auf search gesetzt. Im Gegensatz zur normalen Suche kann die Profisuche über mehrere Eigenschaften durchgeführt werden. Pflicht ist die Angabe des Parameters dosearch mit dem Wert 1, um die Suche zu initialisieren.
    ParameterBedeutungWertebereichDefault
    dosearchFlag für Profisuche1 (fixed)1
    kKontextjazz|poprock|classic|movie|books|score
    Folgende Parameter sind abhängig vom gewählten Kontext (bzw. der Rubrik):
    Musik (Jazz, Pop & Rock, Klassik)
    ParameterBedeutungWertebereichDefault Wert
    titelArtikel-Titel(string)
    interpretMusik-Interpret(string)
    labelMusik-Label(string)
    tracksLiedertitel(string)
    preisbisPreis-Bereich(integer)
    orderbySortierunginterpret|date|preisdate

    Filme (Movie)
    ParameterBedeutungWertebereichDefault Wert
    genreFilm-Kategorie(string)
    titelArtikel-Titel(string)
    tracksNamen(string)
    preisbisPreis-Bereich(integer)
    orderbySortierungtitel|date|preisdate

    Bücher (Books)
    ParameterBedeutungWertebereichDefault Wert
    ctxtitelBuch-Titel(string)
    ctxautorBuch-Autor(string)
    ctxverlagVerlag(string)
    preisbismax. Preis(integer)
    booklangSpracheDeutsch|Englischalle
    orderbySortierungtitel|date|preisdate

    Noten
    ParameterBedeutungWertebereichDefault Wert
    titelTitel/Werk(string)
    interpretKomponist/Texter(string)
    ctxverlagVerlag(string)
    antholBand/Reihe(string)
    kategorieJPC-Kategorie(integer)
    preisbisPreis-Bereich(integer)
    Beispiele: 
      http://www.jpc.de/jpcng/home/xml/-/task/search/dosearch/1/k/jazz/titel/ballads+world
  http://www.jpc.de/jpcng/home/xml/-/task/search/dosearch/1/k/books/titel/heidi/preisbis/5
  http://www.jpc.de/jpcng/home/xml/-/task/search/dosearch/1/k/poprock/interpret/enya/orderby/interpret

  2. Antworten

    Die Antworten bestehen aus wohlgeformten, dem Schema entsprechenden XML-Dokumenten. Diese beschreiben die Ergebnisliste der gefundenen Artikel. Dabei kann die Ergebnisliste natürlich auch leer sein. Die gefundenen Artikel besitzen folgenden Aufbau.

    Beispiel: 
      <artikelliste xsi:schemaLocation="http://www.jpc-partner.de/doku/jpc.xsd" type="detail" count="1">
     <artikel>
        <arttyp>1</arttyp>
        <hnum>8367974</hnum>
        <label>Sony/BMG</label>
        <typnum>2</typnum>
        <genre>Pop</genre>
        <genrenum>42</genrenum>
        <interpret>Dylan, Bob</interpret>
        <titel>Modern Times</titel>
        <inhalt>Thunder on the mountain;Spirit on the water;Rollin' and tumblin';When the deal goes down;Somday
        baby;Workingman's blues No. 2;Beyond the horizon;Nettie Moore;The levee's gonna break;Ain't talkin';+ DVD:Blood in my
        eyes;Love sick (live 'Grammy' version);Things have changed ('Wonder Boys' promo video);Cold irons
        bound (live video)</inhalt>
        <info>***CD + DVD</info>
        <jahr>2006</jahr>
        <anzmed>1</anzmed>
        <ean13>0828768830628</ean13>
        <is_sampler>1</is_sampler>
        <lagerbestand>Artikel am Lager</lagerbestand>
        <tidisplkern>Modern Times</tidisplkern>
        <isnew>1</isnew>
        <isnew30>1</isnew30>
        <preis>16.99</preis>
        <voe_datum>25.08.2006</voe_datum>
        <artikelart>CD</artikelart>
        <images>
           <image>
              <size>thumb</size>
              <back>front</back>
              <url>http://www.jpc.de/image/thumbnails/front/0/8367974.jpg</url>
              <width>300</width>
              <height>252</height>
           </image>
           <image>
              <size>cover</size>
              <back>front</back>
              <url>http://www.jpc.de/image/cover/front/0/8367974.jpg</url>
              <width>300</width>
              <height>252</height>
           </image>
           <image>
              <size>cover</size>
              <back>rear</back>
              <url>http://www.jpc.de/image/cover/rear/0/8367974.jpg</url>
              <width>300</width>
              <height>254</height>
           </image>
           <image>
              <size>middle</size>
              <back>front</back>
              <url>http://www.jpc.de/image/middle/front/0/8367974.jpg</url>
              <width>150</width>
              <height>126</height>
           </image>
           <image>
              <size>blot</size>
              <back>front</back>
              <url>http://www.jpc.de/image/blot/front/0/8367974.jpg</url>
              <width>25</width>
              <height>21</height>
           </image>
        </images>
        <soundinfos>
           <disk>
              <number>1</number>
              <track>
                 <number>1</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_01.wma</url>
              </track>
              <track>
                 <number>2</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_02.wma</url>
              </track>
              <track>
                 <number>3</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_03.wma</url>
              </track>
              <track>
                 <number>4</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_04.wma</url>
              </track>
              <track>
                 <number>5</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_05.wma</url>
              </track>
              <track>
                 <number>6</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_06.wma</url>
              </track>
              <track>
                 <number>7</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_07.wma</url>
              </track>
              <track>
                 <number>8</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_08.wma</url>
              </track>
              <track>
                 <number>9</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_09.wma</url>
              </track>
              <track>
                 <number>10</number>
                 <url mimetype="audio/x-ms-wma">http://www.jpc.de/sound/836/8367974_10.wma</url>
              </track>
           </disk>
        </soundinfos>
     </artikel>
  </artikelliste>

  3. Schema

  4. Beispiel-Programm

    Das Beispiel-Programm besteht aus einem einfachen Stück php-Code, der die wichtigsten Funktionen der XML-Schnittstelle verdeutlichen soll. Es wurden bewusst nur Teilbereiche implementiert, damit die Arbeitsweise verdeutlicht werden kann, ohne auf Spezialfälle eingehen zu müssen.

  5. Links

    XML Einführung
    Spezifikationen
    XML Schema Spezifikation
    Daten-Typen
    XML Schema Checking Service
    Best practices
    Programmier-SchnittstellenPHP

  6. Anhang

    Artikelmedien

    Eine Suche kann auf eines der folgenden Medien beschränkt werden.

    MediumBeschreibung
    WertBedeutung
    BuchBuch
    CDAlbum-CD
    CDMCD-Maxi
    CDRPC-CDROM
    DDDual Disc
    DVADVD-Audio
    DVDDVD
    DVRPC DVD-ROM
    DVPDVD-Plus
    DVSDVD-Single
    Div.Diverses
    LPVinyl-LP
    MAXVinyl-Maxi
    MCMusik-Kassette
    MDMini-Disc
    NotenNotenblätter
    SACDSuper Audio-CD
    SINVinyl-Single
    SpieleBrett- und Gesellschaftsspiele
    VIDVHS-Video
    MP3MP3 CD
    HDHD DVD
    BRBlu-ray Disc

Last changed: 2006-10-12 12:05:38