APIs
The interfaces below are exposed by services of the Velocity Interoperability Network. Each follows one of the published Network standards and is recorded in the API Catalogue, which is the authoritative register of identifier, version and status. Documentation for each available interface is published on this site and linked from the table.
| API | Provider | Standard | Status | Documentation |
|---|---|---|---|---|
| Registry lookup | Member Registry | VIN-4 Registry Data Model | Interim | Read the documentation |
| Identity assertion | Identity Service | VIN-2 Identity Federation | Interim | Read the documentation |
| Incident submission | Status Service | VIN-3 Incident Reporting Format | Interim | Read the documentation |
| Notice feed | Official Register | VIN-5 Message Envelope | Interim | Read the documentation |
| Conformance record lookup | Developer Portal | VIN-4 Registry Data Model | Planned | Not yet published |
| Standards feed | Developer Portal | VIN-5 Message Envelope | Planned | Not yet published |
Requirements common to every interface. Every request to and response from a Network interface is carried in the envelope defined by VIN-5 Message Envelope, and every request carries an identity assertion issued under VIN-2 Identity Federation for the system that sends it. A developer who has implemented the envelope and obtained an assertion can call any interface in the catalogue; what differs between interfaces is only the payload. The envelope carries the following fields.
| Field | Meaning |
|---|---|
| Envelope identifier | Unique reference of the message, generated by the sender. |
| Sender | System identifier of the sending system, as registered with the Identity Service. |
| Recipient | System identifier of the receiving system or Network service. |
| Sequence number | Increases by one for each message from the sender to the recipient, so that a gap or repeat can be detected. |
| Timestamp | Time of sending. A message more than five minutes old is refused. |
| Assertion | An identity assertion for the sending system, obtained from the Identity Service. |
| Payload type | The name of the operation requested, or of the result returned. |
| Payload | The request or response defined by the interface. |
| Signature | Signature of the sender over all other fields. |
Status of an interface. The status recorded against an interface in the catalogue has one of the following meanings. An interface moves from Planned to Interim to Confirmed, and may at any stage be Withdrawn with notice.
- Planned
- Notified to the Developer Portal and assigned a catalogue identifier, but not yet available. No documentation is published, and no version is assigned, until the interface becomes Interim.
- Interim
- Available to member organisations and documented on this site at a version below 1.0. The interface may change before it is confirmed, and each change is announced on its documentation page and recorded in the catalogue.
- Confirmed
- Documented in full and stable at Version 1.0 or later. Changes are made only by issuing a new version of the standard it follows, with the notice set out under Versioning.
- Withdrawn
- No longer offered, after six months' notice. A withdrawn interface remains listed for reference with the date of its withdrawal, and its documentation remains published.
Obtaining access. Access to Network interfaces is not applied for separately. A system that meets the conditions below may call any Interim or Confirmed interface; the provider refuses requests from systems that do not.
Step 1: Confirm that the organisation is listed as Active
Only a system operated by a member organisation listed on the register with the status Active may call a Network interface. The listing may be checked through the registry lookup.
Step 2: Register the system with the Identity Service
The member organisation registers each system that will call interfaces, through the procedures of the Identity Service. The system identifier issued on registration is carried in every envelope the system sends.
Step 3: Declare conformance to VIN-1 and VIN-5
Before a system sends its first message it must be the subject of a declaration of conformance to the Interoperability Baseline and the Message Envelope, sent to the Developer Portal as described under Conformance.
Step 4: Obtain an assertion and send the request
The system requests an identity assertion for itself from the Identity Service, places it in the envelope with the request, signs the envelope and sends it to the provider named in the catalogue.
Step 5: Handle the response and any error condition
The response is returned in an envelope carrying the sequence number of the request. The error conditions of each interface, and what a caller should do on receiving each, are set out in its documentation.
Rate of requests. Unless the documentation of an interface states otherwise, a provider may refuse requests from a system that sends more than 600 in one minute. A system that needs to make many requests should prefer the operations, such as the registry lookup's Retrieve status, that providers exempt from the limit, or subscribe to a feed rather than poll.
Questions about an interface may be sent to contact@developer.gov.vin and are passed to the provider where they concern its operation. The procedure for declaring conformance is set out under Conformance; the rules on versions under Versioning; and the terms used on this page in the Glossary.