================
Webservices Pure
================

:Author: Fred Vos

============
Even geleden
============

.. image:: old.png

====
Pure
====

- Vervanger van Metis en ARNO
- Bestaande koppelingen site + Webwijs behouden
- Copy/paste-koppelingen live maken
- Koppelingen uitbreiden

===========
Webservices
===========

Benaderen van een programma/databank via een web-protocol (HTTP)

SOAP
  Simple Object Access Protocol

REST
  Representational State Transfer (HTTP request methods GET, HEAD, PUT, POST, DELETE)

=========================
REST in Pure (alleen GET)
=========================

URLs:

Productie

::

  https://pure.uvt.nl/ws/rest/<resource>
      ?querystring

Test

::

  https://test.pure.uvt.nl/ws/rest/<resource>
      ?querystring

=================
Output bijgewerkt
=================

Om op scherm te passen:

- Fractie getoond
- Namespacedeclaraties vervallen
- Data verwijderd
- Whitespace verwijderd
- Gebruik van '...' om lange strings in te korten

===========
Voorbeeld 1
===========

::

  https://pure.uvt.nl/ws/rest/publication
      ?searchString=africa

Alle publicaties gezocht op africa, recent ingevoerd/gewijzigd eerst (sortering is aan te passen)

======
Output
======

::

  <?xml version="1.0" encoding="UTF-8"?>
  <publication-template:GetPublicationResponse requestId="">
    <core:count>229</core:count>
    <core:result>
      <core:content uuid="06a9dd0f-7629-48e3-a64b-c4b7210cdd5b" xsi:type="stab:ContributionToJournalType">
        <core:portalUrl>https://pure.uvt.nl/portal/en/publications/mobile-phones-and-safety-in-developing-countries(06a9dd0f-7629-48e3-a64b-c4b7210cdd5b).html</core:portalUrl>
        <publication-base_uk:title>Mobile phones and safety in developing countries</publication-base_uk:title>
        <publication-base_uk:publicationDate>
          <core:year>2015</core:year>
        </publication-base_uk:publicationDate>
        ...

======
Window
======

Waarde in <core:count> geeft aan hoeveel er in totaal zijn.

In querystring opgeven welke records.

window.offset
  Beginrecord (0=eerste, default=0)

window.size
  Aantal records (default=20)
  
Voorbeeld: ``&window.offset=30&window.size=30`` voor records 31 t/m 60.


===================
Lijst van resources
===================

Lijst alle resources: ``https://pure.uvt.nl/ws/rest/bla``

::

  The requested resource '/bla' does not exist.
  Maybe you meant 'event'?. Known valid resources are :
  activity
  activity.current
  aggregationstrategies
  aggregationstrategies.current
  allowedfamilies
  allowedfamilies.current
  ...

Bijna alle resources hebben een .current-variant.

=====================
Current versus stable
=====================

- Current soms meer mogelijkheden
- Current onbetrouwbaar
- Current andere namespaces

===========
Voorbeeld 2
===========

::

  https://pure.uvt.nl/ws/rest/organisation
      ?organisationIds.value=50000115
      &rendering=xml_long
      &window.size=1

Info over een organisatie (naam, UUID).

======
Output
======

::

  <?xml version="1.0" encoding="UTF-8"?>
  <organisation-template:GetOrganisationResponse>
    <core:count>1</core:count>
    <core:result>
      <core:content uuid="10d3304c-8e91-4a02-bf64-ab99cfad7a55" xsi:type="stab:UKOrganisationType">
        <core:portalUrl>https://pure.uvt.nl/portal/en/organisations/tilburg-law-school(10d3304c-8e91-4a02-bf64-ab99cfad7a55).html</core:portalUrl>
        <stab1:name xmlns:stab1="http://atira.dk/schemas/pure4/model/template/abstractorganisation/stable">
          <core:localizedString locale="en_GB" formatted="false">Tilburg Law School</core:localizedString>
        </stab1:name>


===========
Voorbeeld 3
===========

::

  https://pure.uvt.nl/ws/rest/publication
      ?associatedOrganisationUuids.uuid=10d3304c-8e91-4a02-bf64-ab99cfad7a55
      &associatedOrganisationAggregationStrategy=RecursiveContentValueAggregator
      &orderBy.property[0]=publicationYearMonthDay
      &orderBy.property[0].descending=true
      &orderBy.property[1]=created
      &orderBy.property[1].descending=true
      &window.offset=0&window.size=20
      &rendering=xml_long

20 meest recente publicaties (publicatiedatum) van TLS en suborganisaties met uitgebreide informatie.

==================
Rendering - altijd
==================

xml_short (default)
  Heel veel XML
  
xml_long
  Nog iets meer XML

================
Rendering - soms
================

long
  Veel HTML

short
  Wat minder HTML

Probeer &rendering=bla voor alle opties in de foutmelding
  
=======================
Rendering - publicaties
=======================

apa
  APA (HTML)

BIBTEX
  BibTex (HTML)

RIS
  RIS (HTML)

===========
Voorbeeld 4
===========

::

  https://pure.uvt.nl/ws/rest/organisation
      ?parentUuids.uuid=10d3304c-8e91-4a02-bf64-ab99cfad7a55
      
Organisaties direct onder TLS.

UUID uit eerdere response.

===========
Voorbeeld 5
===========

::

  https://pure.uvt.nl/ws/rest/publication
      ?associatedPersonSourceIds.value=199788
      &window.size=5

De 5 meest recent ingevoerde/aangepaste publicaties van persoon met ID (ANR) 199788

===========
Voorbeeld 6
===========
  
::

  https://pure.uvt.nl/ws/rest/person
      ?personEmployeeIds.value=199788
      &rendering=xml_long

Informatie over persoon met ANR 199788

============
Documentatie
============

Via ``/ws/doc/rest/reference.pdf`` kan je documentatie laten **genereren** op basis van de WSDL van Pure.

Kost veel tijd en processorkracht en levert PDF op van 1760 pagina's!

Opslaan dus en eens in de zoveel tijd een keer opnieuw maken.

Requests in willekeurige volgorde.

Zoek in PDF naar ``/rest/<resource>``, bijvoorbeeld ``/rest/publication`` en sectie daaronder 'Request parameters' geeft je lijst met mogelijkheden.

=====================
Belangrijke resources
=====================

- ``publication``
- ``organisation``
- ``person``

=======
Nadelen
=======

- Complexe lelijke XML (CUSTPURE-282)
- Instabiele API

==============
XML Namespaces
==============

::

  <?xml version="1.0" encoding="UTF-8"?>
  <wsdl-organisation:GetOrganisationsResponse
      xmlns:wsdl-organisation="http://atira.dk/schemas/pure4/template/wsdl/organisation/stable"
      xmlns:core="http://atira.dk/schemas/pure4/model/core/stable"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:organisation="http://atira.dk/schemas/pure4/model/abstractorganisation/stable"
      xmlns:extensions="http://atira.dk/schemas/pure4/model/extensions/stable" requestId="">
    <core:count>1</core:count>
    ...

(toelichting over prefixes, URI's e.d.)

==========
Parsen XML
==========

**XML ziet er verradelijk simpel uit, maar is dat niet!**

Een handjevol mensen op de hele wereld snapt XML helemaal.

Alle talen hebben redelijke tot goede libraries om XML te parsen.

Met benadering als strings neem je veel risico.

**Zelf XML parsen is niet stoer maar stom!**

=======
Vragen?
=======

.. header::

        Pure Webservices

.. footer::

        Tilburg University, 2015