Representations for APIs

API Course Politecnico di Milano

Erik Wilde , API Academy, CA Technologies
March 28, 2018

Creative Commons License [http://creativecommons.org/licenses/by/3.0/]

This work is licensed under a CC
Attribution 3.0 Unported License
[http://creativecommons.org/licenses/by/3.0/]

Contents Erik Wilde : Representations for APIs

Contents

Introduction

Outline (Introduction)

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
Introduction Erik Wilde : Representations for APIs

(3) Digital Shadows



Introduction Erik Wilde : Representations for APIs

(4) Resources



Introduction Erik Wilde : Representations for APIs

(5) Digital Representations



Introduction Erik Wilde : Representations for APIs

(6) Vocabularies



Introduction Erik Wilde : Representations for APIs

(7) Validation



What and How to Represent

Outline (What and How to Represent)

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
What and How to Represent Erik Wilde : Representations for APIs

(9) What to Represent



What and How to Represent Erik Wilde : Representations for APIs

(10) Objects vs. Documents



What and How to Represent Erik Wilde : Representations for APIs

(11) Object Example (JSON)

{
  "Image": {
      "Width":  800,
      "Height": 600,
      "Title":  "View from 15th Floor",
      "Thumbnail": {
          "Url":    "http://www.example.com/image/481989943",
          "Height": 125,
          "Width":  100
      },
      "Animated" : false,
      "IDs": [116, 943, 234, 38793]
    }
}


What and How to Represent Erik Wilde : Representations for APIs

(12) Document Example (XML)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "section.dtd">
<document>
 <section id="sgml" author="dret">
  <title>Standard Generalized Markup Language (SGML)</title>
  <p>SGML is an ISO standard ...</p>
  <section id="sgml-syntax" author="bob">
   <title>SGML Syntax</title>
   <p>SGML uses markup, which is ...</p>
  </section>
 </section>
 <section id="xml" author="bob">
  <title>Extensible Markup Language (XML)</title>
  <p>XML is based on SGML (Section <ref name="sgml"/>) ...</p>
  <p type="example">XML can be used ...</p>
  <section id="xml-syntax" author="dret">
   <title>XML Syntax</title>
   <p>Section <ref name="sgml-syntax"/> describes ...</p>
  </section>
 </section>
</document>


What and How to Represent Erik Wilde : Representations for APIs

(13) Profiles



Extensible Markup Language (XML)

Outline (Extensible Markup Language (XML))

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(15) XML Origins and History



Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(16) Basic Concepts: Elements and Attributes

<?xml version="1.0" encoding="UTF-8"?>
<element>
 <subelement attribute="value">Content</subelement>
 <subelement a2="value2">More Content</subelement>
 <empty-element a3="v3"></empty-element>
 <empty-element a4="v4" a5="v5"/>
</element>


Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(17) XML is Trees



Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(18) XML Content and Names

XML documents can use a wide array of characters. They are defined by Unicode [http://www.unicode.org/], which in Version 5.0 defines more than 100'000 characters (#100'000 added in 2005).

<?xml version="1.0" encoding="UTF-8"?>
<JAPANESE>
 <TITLE>専門家リスト </TITLE>
 <ITEM>アシム・アブドゥラー氏(コマースネット事務局長)</ITEM>
 <ITEM>アラン・A・メッコラー氏(メッコラーメディア会長兼CEO)</ITEM>
 <ITEM>アラン・サルディッチ氏(メトリコムディレクター)</ITEM>
 <ITEM>ウィスター・ウォルコット氏(パイロットネットワーク・サービシズ副社長)</ITEM>
 <ITEM>・エリック・リンゲワルド氏(ビー・インク副社長)</ITEM>
 <ITEM>ジェームス・L・バークスデール氏(ネットスケープ・コミュニケーションズ社長)</ITEM>
</JAPANESE>
<?xml version="1.0" encoding="UTF-8"?>
<文書 改訂日付="1999年3月1日">
 <題>サンプル</題>
 <段落>これはサンプル文書です。</段落>
 <!-- コメント -->
 <段落>会社名</段落>
 <図面 図面実体名="サンプル" />
</文書>


Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(19) Elements



Extensible Markup Language (XML) Erik Wilde : Representations for APIs

(20) Attributes

 <section id="xml" author="bob">
  <title>Extensible Markup Language (XML)</title>
  <p>XML is based on SGML (Section <ref name="sgml"/>) ...</p>
  <p type="example">XML can be used ...</p>
  <section id="xml-syntax" author="dret">
   <title>XML Syntax</title>
   <p>Section <ref name="sgml-syntax"/> describes ...</p>
  </section>
 </section>


Erik Wilde : Representations for APIs

(21) Mixed Content

The term Mixed content in XML refers to elements which have text content mixed with elements [http://www.w3.org/TR/xml/#sec-mixed-content]. What these elements do depends on the elements smiley.gif, but the important point is that they are on the same level as the text nodes of the mixed content.

<p>The term <em>Mixed content</em> in XML refers to elements <a href="http://www.w3.org/TR/xml/#sec-mixed-content">which have text content mixed with elements</a>. What these elements do depends on the elements <img style="height : 1em" src="smiley.gif"/>, but the important point is that they are on the same level as the text nodes of the mixed content.</p>
XML tree for mixed content

Erik Wilde : Representations for APIs

(22) Mixed Content Usage



Erik Wilde : Representations for APIs

(23) Semantics



JavaScript Object Notation (JSON)

Outline (JavaScript Object Notation (JSON))

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
JavaScript Object Notation (JSON) Erik Wilde : Representations for APIs

(25) JSON and XML



JavaScript Object Notation (JSON) Erik Wilde : Representations for APIs

(26) JSON Basics



JavaScript Object Notation (JSON) Erik Wilde : Representations for APIs

(27) JSON Structure



JavaScript Object Notation (JSON) Erik Wilde : Representations for APIs

(28) JSON Example

{
  "Image": {
      "Width":  800,
      "Height": 600,
      "Title":  "View from 15th Floor",
      "Thumbnail": {
          "Url":    "http://www.example.com/image/481989943",
          "Height": 125,
          "Width":  100
      },
      "Animated" : false,
      "IDs": [116, 943, 234, 38793]
    }
}


JavaScript Object Notation (JSON) Erik Wilde : Representations for APIs

(29) JSON and I-JSON



Resource Description Framework (RDF)

Outline (Resource Description Framework (RDF))

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
Resource Description Framework (RDF) Erik Wilde : Representations for APIs

(31) Describing Resources



Resource Description Framework (RDF) Erik Wilde : Representations for APIs

(32) Triple Example

<Bob> <is a> <person>.
<Bob> <is a friend of> <Alice>.
<Bob> <is born on> <the 4th of July 1990>. 
<Bob> <is interested in> <the Mona Lisa>.
<the Mona Lisa> <was created by> <Leonardo da Vinci>.
<the video 'La Joconde à Washington'> <is about> <the Mona Lisa>.


Resource Description Framework (RDF) Erik Wilde : Representations for APIs

(33) Two Views of RDF



Resource Description Framework (RDF) Erik Wilde : Representations for APIs

(34) Triples as a Graph

Informal graph of the sample triples

More Representation Formats

Outline (More Representation Formats)

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
More Representation Formats Erik Wilde : Representations for APIs

(36) Collections as a Pattern



More Representation Formats Erik Wilde : Representations for APIs

(37) Comma-Separated Values (CSV)



More Representation Formats Erik Wilde : Representations for APIs

(38) HTTP Problem Details



More Representation Formats Erik Wilde : Representations for APIs

(39) HTTP Problem: JSON

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": [
    "/account/12345",
    "/account/67890"
  ]
}


More Representation Formats Erik Wilde : Representations for APIs

(40) HTTP Problem: XML

<problem xmlns="urn:ietf:rfc:7807">
  <type>https://example.com/probs/out-of-credit</type>
  <title>You do not have enough credit.</title>
  <detail>Your current balance is 30, but that costs 50.</detail>
  <instance>https://example.net/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>https://example.net/account/12345</i>
    <i>https://example.net/account/67890</i>
  </accounts>
</problem>


Conclusions

Outline (Conclusions)

  1. Introduction [5]
  2. What and How to Represent [5]
  3. Extensible Markup Language (XML) [6]
  4. JavaScript Object Notation (JSON) [5]
  5. Resource Description Framework (RDF) [4]
  6. More Representation Formats [5]
  7. Conclusions [2]
Conclusions Erik Wilde : Representations for APIs

(42) Language Matters



Conclusions Erik Wilde : Representations for APIs

(43) Thanks! Q&A

What's Next?

March 28, 2018 API Course Politecnico di Milano