Re: [coel] Question on Format

[Paul.Bruton@tessella.com]

Tessella Ref: NPD/8140/CL/CSC/2017Feb01/15:44:42

Hi David,

I prefer the second example. 

As to examples, take a look at the altered
version of the BAP here (which was never put on Kavi). I put the example
in a subsection "example (non-normative) and I also tried making the
error response more narrative, liek Patrick suggested.

Regards

Paul

---

Paul Bruton, BSc, PhD

Consultant

Email: paul.bruton@tessella.com
Mobile: +44 (0)7557 916535
Skype: paulbruton.skype

Chadwick House, Suite 410, Birchwood Park, Warrington, WA3 6AE, UK
Tessella is part of the Altran Group - www.tessella.com

Please consider the environment and do not print this e-mail unless you really need to.

This message is commercial in confidence and may be privileged. It is intended for the addressee only. Access to this message by anyone else is unauthorised and strictly prohibited. If you have received this message in error, please inform the sender immediately. Please note that messages sent or received by the Tessella e-mail system may be monitored and stored in an information retrieval system. Tessella is Registered in England No. 1466429




From:        "david.snelling@uk.fujitsu.com" <david.snelling@uk.fujitsu.com>
To:        "coel@lists.oasis-open.org" <coel@lists.oasis-open.org>
Date:        01/02/2017 12:13
Subject:        [coel] Question on Format
Sent by:        <coel@lists.oasis-open.org>

---

Folks,

 

What format do we want for the request/response descriptions?

 

The info request looks like this:

 

Questions to answer at the bottom.

 

1.1.1 Information Request

Every Data Engine SHALL publish its Data Engine Home URI.
Performing a GET on this URI SHALL return general information about the
Data Engine as JSON object.

Method	Request	Response Status	Response Content-Type	Response Body
GET	None	200 (OK)	application/json	JSON object
POST	Any	405 (Method Not Allowed)	None	None

Format for the returned JSON Object:

Name	Value	Description	REQUIRED
AtomsURI	String	The URI of the Atoms service encoded as a string.	Yes
QueryURI	String	The URI of the Query service encoded as a string.	Yes
ManagementURI	String	The URI of the Management service encoded as a string.	Yes
ServerTime	Integer	Current server time in UTC as a Unix timestamp.	Yes
AtomsStatus	String	The current status of the Atoms service encoded as a string. It MUST be one of “Up”, “Down”, or “Unknown”.	Yes
QueryStatus	String	The current status of the Query service encoded as a string. It MUST be one of “Up”, “Down”, or “Unknown”.	Yes
ManagementStatus	String	The current status of the Management service encoded as a string. It MUST be one of “Up”, “Down”, or “Unknown”.	Yes

The JSON object of the response MAY contain additional
fields with information about the Data Engine. 

 

Most of the operations in the current specs look like
this:

API	Description
POST service-provider/operator	Create an Operator identity within the Data Engine permitting that operator to create and register Consumers.

1.1.2 Request

Parameter Name	Description	Type
OperatorID	A Pseudonymous Key generated by an IDA and associated with the Operator being registered.	String: Format defined in [COEL_IDA-1.0].
TimeStamp	Time stamp of the OperatorID indicating when the IDA created this Pseudonymous Key.		DateTimeString: Format defined in [COEL_IDA-1.0].
Signature	Signature proving that an IDA created this OperatorID.		String: Format defined in [COEL_IDA-1.0].

Media type: 

application/json, text/json

1.1.3 Response 

If successful, an HTTP status code of 200 OK MUST
be returned. If unsuccessful, an HTTP error code SHOULD be returned and
a JSON object MAY be returned providing some explanation of the failure.


If validation of the OperatorID fails, with a 410 (Gone)
error from the IDA, an error 410 (Gone) should be returned.

Parameter Name	Description	Type
Reason	An optional description of why the registration failed.	String:

Media type: 

application/json, text/json

 

Which do we like?

 

Also, are we putting examples in the sections or only
in the longer example section?

 

--

Take care:

    Dr. David Snelling < David
. Snelling . UK . Fujitsu . com >

    Senior Research Fellow / Fujitsu Distinguished
Engineer

    Fujitsu Laboratories of Europe Ltd.

    +44-7590-293439 (Mobile)

 

 

Unless otherwise stated, this email has been sent from
Fujitsu Services Limited (registered in England No 96056); Fujitsu EMEA
PLC (registered in England No 2216100) both with registered offices at:
22 Baker Street, London W1U 3BW;  PFU (EMEA) Limited, (registered
in England No 1578652) and Fujitsu Laboratories of Europe Limited (registered
in England No. 4153469) both with registered offices at: Hayes Park Central,
Hayes End Road, Hayes, Middlesex, UB4 8FE. 
This email is only for the use of its intended recipient.
Its contents are subject to a duty of confidence and may be privileged.
Fujitsu does not guarantee that this email has not been intercepted and
amended or that it is virus-free.

Attachment: BAP-v1.0-wd02 - with markup.docx
Description: Binary data