ausdigital/restful-framework

Legacy repository - content has moved as defined in read.me

restful-framework's Issues

community process

As a community stakeholder
I need a "clear process" for engagement and participation
so that I can testify to my requirements and make technical contributions

This elaborates on https://github.com/ausdigital/framework-docs#how-to-participate (and extends #2).

I propose the effort would benefit from a simple, formal and transparent process where enhancement proposals are discussed by the community and promoted into the spec (or not) based on evident technical merit.

The OSI approach to Open Standards is probably a useful guide:

• https://opensource.org/osr-intro
• https://opensource.org/osr-rationale
• https://opensource.org/osr-compliance

Yes, this could (probably should) be implemented with GitHub tickets, so we don't necessarily need new features to support this. The suggestion is that we adopt a pragmatic workflow for proposing, discussing and deciding on changes, and the workflow and decision making should be compatible with a community-led process.

I would consider the community process a success in the following scenario:

Given I am a community member with an enhancement idea
And I have read the public web content about the community process
When I submit my enhancement proposal (in the form of a GitHub ticket)
Then I understand how it will be assessed on technical merit
And the discussions of technical merit are conducted in the open
And I am able to participate in the discussions of technical merit
And I understand that the decision to accept or reject the enhancement proposal was made in a fair and reasonable way (even If I do not agree with the decision)

Create stand-alone 'how to participate' section in README.md (somewhere up-front)

It may be worth making it clearer that this is intended as an open & collaborative process. Specifically, it seems like there's three ways to participate:

• Raise issues
• Make pull requests
• Contact in person (e.g. via linked in) if more direct participation is desired

I'd do this myself, but I'm going to be tied up with something for the next little while...

invoice API semantic mismatch to OASIS 1.0

There are two kinds of semantic mismatch between the current /invoice/ swagger spec and the OASIS/UBL eInvoicing spec.

1. Superfluous verbs. Don't need GET, PUT and DELETE /invoice/ endpoints. GET makes sense (processing state metadata) but it's not in the spec (enhancement proposal? - see #6).
2. Missing ACK noun (/business_response/?). These should also be POSTed (it takes two to tango).

Both POSTs should probably return a GUID (for out of band status enquiry now, and possible future GET status/processing-metadata enquiry).

And, aren't there subtypes of invoice noun? should they have their own POST endpoints? I think it might be nicer to map validation rules to endpoints, but they could also be tested against payload types.

Test issue

Test issue to check migration

identify examples of community process

Before re-inventing the wheel (wrt: #3), let's identify examples of "community process" that may be suitable for this open standard.

update docs to reflect community process

further to #4, we need to update docs to reflect http://rfc.unprotocols.org/spec:2/COSS/ as a community process

Enhancement Proposal: GET linked invoice/ACK metadata

Further to conversation about #5, suggest we consider enhancement to 1.0 version of the protocol that allows access to data about the state of an invoice/receipt by utilising gateway-generated GUIDs and GET verbs.

As an Australian Business
I need the ability to automatically monitor the status of my invoices
so that I have timely, low cost information about my accounts receivable

For example, if successful submission (response code 200) of POST /invoices/ returned data containing a gateway submission GUID, then GET /invoices/<GUID>/ (at the same gateway) could return data about the state of the submission. (subsequent analysis required - what is the state transition model of a submission? it's it more complicated than "unacknowledged" or "acknowledged"?)

As an Australian Business
I need the ability to link to the status of my invoices
So that I can chose to share access to that information with Interested Parties

and also:

As an Interested Party
I need the ability to monitor the status of 3rd party invoices
So that I can inform the management of my counter-party risk

This implies that the data returned from POST /invoices/ has two properties:

• Acknowledgement metadata (might be a link to the receipt acknowledgement URL)
• Some kind of signature that can be used to verify claims about the invoice that was submitted

For example, an Australian Business might tell their Financier (Interested Party) "I sent this invoice, and here is the gateway endpoint for the submission", and the financier would be able to verify that claim (of submission - same date, amount, etc) and monitor it's status (hmm, queried/disputed). Financiers making use of this information may be able to provide more price-competitive credit through a combination of lower operating costs (automation) and more precise risk management.

Another example might be a debt collection service that is sent verifiable invoices / status endpoints, and who uses them (in combination with payment data) to drive an automated debt recovery protocol.

As an Australian Business
I need the ability to prove an invoice payload corresponds to an invoice GUID
So that interested parties can verify invoice status information that I have shared with them

Is this all-or-nothing (one signature for the whole invoice), or would an Australian Business want to share some but not all data from a particular invoice with a third party who then needs to verify it?

Similarly, a successful POST /responses/ (or whatever the noun is, it's still not specified in the spec) should return a data containing a GUID, such that GET /responses/<GUID>/ will describe the state of the acknowledgement. This may or may not be a duplication of the data available in the GET /invoices/<GUID> endpoint. My preference is that the /invoice/ endpoint contains a link to the relevant /responses/ endpoint (for better cache performance of GET /invoices/ subsequent to transitioning out of null-acknowledgement state), but either could work I think.

Again, modelling the state machine of acknowledgements would be an interesting exercise - are there different stages that could be mapped to standard accounting practice? For example, is an invoice first mechanically acknowledged (valid submission received by gateway, forwarded to business), then some kind of human acknowledgement (received by business but no comment about liability), then some kind of affirmation (or dispute - indicate intention to pay/not pay)? Perhaps even a "the cheque's in the mail" assertion...

Note: I'm assuming GUID is essentially random and that /invoice/ and /response/ are different values of GUID, even if the response corresponds to the invoice.

If an invoice has been acknowledged, then the GET /invoices/<GUID> should contain a URL for the GET /responses/<GUID>. In other words, an invoice should link to it's response (if any) but not necessarily the other way round.