Archive of shop rest specification works

Warning:
this page was inteneded for specification works, the final documentation of each services can be found here:

New extraction interface specification page

Content:

Service name and URL

TODO: Choose a name, and URL pattern for this new service.
For now, it is:
index.php?option=com_easysdi_shop&task=extractioninterface

WPS compliance

WPS compliance is not maintained for this service

Method: GetOrders

url : index.php?option=com_easysdi_shop&task=extractioninterface.getorders

This method lists the new ("sent" status) orders (of both orders and estimate types).
Response is sent in raw XML (without any envelope like SOAP or WPS, see Response format).
The service will expose orders of:
  • All providers (organisms) : when used with the "global extraction account" credentials
  • On provider : when used with the "exctraction account" set in an organism

Parameters:

  • none

Response format:

In attachment:

  • An example of XML response (sdi-getOrders-response-sample.xml)
  • The proposed XSD (sdi-getOrders.xsd)
Remarks:
Main differences between WPS and new service:
- Products are under their supplier
- Added easySDI version
- Added id and guid when available
- Supplier has been extended to been a full organism
- Pricing added
- Lower case
- Use attributes instead of elements when logical (to me !)

Questions:
- Is XSD OK? (I'm not an XML schema king ;-) ):
    Types used:
    (http://www.w3.org/TR/xmlschema-2/#built-in-datatypes)
    decimal: for money and percentages.
    string: for guid, and text values
    integer: for IDs
    float: for surface
    base64binary: for XML and PDF attachments
    boolean: for ... booleans (and I suggest to store the as "true" or "false" and not 1 and 0 in XML output)
- What was "SERVER 36" ? I dropped it...
- Tarification profile doesn't have guid...

Upgrades done into xsd (see attachment:getorders.xsd) :
- as an order can have no thirdparty, min/maxOccurs were added to the tierce organism
- guid attribute added to the tarification profile
- metadataId becomes guid and exposes the product guid
- product has a new children named metadata
- xml and pdf are moved into metadata
- metadata's id and guid are exposed as attributes
- name attribute added to the client

Method: SetOrder

url : index.php?option=com_easysdi_shop&task=extractioninterface.setorder

This method allows to set the response for an order.
It's not possible to respond to multiple products in one call. One call = on product of an order.

Only availlable thru POST method.
Use of "multipart/form-data" (see https://www.ietf.org/rfc/rfc1867.txt)

Parameters:

  • datafile (Binary file)
  • remotedatafileurl (String: URL of remote file)
  • remotedatafilename (String: name remote file to display)
  • remotedatafilesize (Double: remote file size in bytes)
  • prodcutstate (String: product state code, see #_sdi_sys_productstate)
  • remark (Multi-line string: optional remark of provider. It is a remark on product, not on order!)
  • price (Decimal : price, taxes included, of the product)
Remark and questions:
 - For the datafile field, the field "filename" in content-disposition MUST be set
   (php uses it to detect files! https://github.com/php/php-src/blob/833e4669832137edbc4526a0d7c10f16396554a0/main/rfc1867.c)
   I suppose content disposition should looks like this (a little RFC reading will be needed here...):
       Content-Disposition: form-data; name="datafile"; filename="fichierShapeCommune.zip" 
 - remotefile* fields are new: it' s a proposal to enhance the current behavior which is
   to put the url of remote file in remark field in case of the data is not sent to the easySDI platform
   but kept on supplier's servers.
 - prodcutstate (String: product state code, see #_sdi_sys_productstate,
   this is a new field since there will be new states for order product #644 (like rejected) )
 - Do we define an encoding for text fields? UTF-8 ?

Parameters rules

Fields that MUST or CAN be set:

+----------+---------------------------------------------------------------------------------------------------------------------------+
|          |                         order response                                                                                    |
|    **    |                            |    |                                                                                         |
|          |                            |    |                                                                                         |
|order type|     estimate<--------------+    +----------------->order                                                                  |
|----------|      |     |                                       |   |                                                                  |
|          |      |     |                                       |   |                                                                  |
|          |      |     |                                       |   |                                                                  |
|          |      |     +---------+               +-------------+   +----------+                                                       |
|          |      v               v               v                            v                                                       |
|status    | rejected          available       rejected                     available                                                  |
|------    |      ¦               ¦               ¦                           |   |                                                    |
|          |      ¦               ¦               ¦                           |   |                                                    |
|          |      ¦               ¦               ¦                           |   +--------------------------------+                   |
|          |      ¦               ¦               ¦                           v                                    v                   |
|storage   |      ¦               ¦               ¦                      local storage                       remote storage            |
|-------   |      ¦               ¦               ¦                      (on easySDI                           (provider's             |
|          |      ¦               ¦               ¦                        platform)                             servers)              |
|          |      ¦               ¦               ¦                         |  |                                  |  |                 |
|          |      ¦               ¦               ¦                         |  |                                  |  |                 |
|          |      ¦               ¦               ¦                +--------+  +---+                  +-----------+  +------+          |
|          |      ¦               ¦               ¦                v               v                  v                     v          |
|pricing   |      ¦               ¦               ¦        predefined in sdi   to be defined    predefined in sdi    to be defined     |
|-------   |      ¦               ¦               ¦        (profile or free)      (fee)        (profile or free)          (fee)        |
|          |      ¦               ¦               ¦                ¦               ¦                  ¦                     ¦          |
|          |      ¦               ¦               ¦                ¦               ¦                  ¦                     ¦          |
|          |      ¦               ¦               ¦                ¦               ¦                  ¦                     ¦          |
|          |      ¦               ¦               ¦                ¦               ¦                  ¦                     ¦          |
|          |      v               v               v                v               v                  v                     v          |
|          |               |               |               |               |               |                     |                     |
|          |               |               |               |               |               |                     |                     |
|          |productstate[1]|productstate[1]|productstate[1]|productstate[1]|productstate[1]|productstate[1]      |productstate[1]|     |
|          |remark[1]      |remark[0-1]    |remark[1]      |remark[0-1]    |remark[0-1]    |remark[0-1]          |remark[0-1]          |
|resulting |               |price[1]       |               |datafile[1]    |price[1]       |remotedatafileurl[1] |price[1]             |
|attributes|               |               |               |               |datafile[1]    |remotedatafilename[1]|remotedatafileurl[1] |
|----------|               |               |               |               |               |remotedatafilesize[1]|remotedatafilename[1]|
|          |               |               |               |               |               |                     |remotedatafilesize[1]|
|          |               |               |               |               |               |                     |                     |
+----------+---------------+---------------+---------------+---------------+---------------+---------------------+---------------------+

** Note: "order type" and "pricing" depends of values given by getOrders method
         "status" and "storage" depends of provider choices

Error handling

On error, service responds with HTTP error code + explanation

Examples:

Error HTTP Code HTTP Message Remark
Accessing the service without credential, or incorrect credentials 401 Unauthorized Unauthorized --
setOrder with incoherent fields in POST 400 Bad Request [Explain missing or extra fields, for example, a file on an "estimate" order] see parameters rules of setOrder method
setOrder on a product of another supplier 403 Forbidden You cannot update this product --
setOrder on an inexistent product 404 Not found The product you try to update does not exists --
setOrder on a state the avoids update (available state) 409 Resource Conflict The product you try to update is already available to client Do we decide that we can "re-update" a product from service?
Not an error
No order for this provider 200 Ok [Empty Orders XML element] This is not an error, there is no "new" orders for this provider