IUID Registry Application Programming Interface (API) Version 5.6. Software User s Manual (SUM)

Transcription

1 IUID Registry Application Programming Interface (API) Version 5.6 Software User s Manual (SUM) Document Version 1.0 May 28, 2014 Prepared by: CACI 50 N Laura Street Jacksonville FL Prepared for: Defense Logistics Agency (DLA)

2 IUID API SUM DRAFT VERSION i REVISION TABLE Version Primary Author Description of Version Date Completed V1.0 CACI Software User Manual

3 IUID API SUM DRAFT VERSION ii TABLE OF CONTENTS 1.0 SCOPE Identification System Overview Document Overview SOFTWARE SUMMARY Software Application Security and Privacy Considerations AUTHENTICATION METHODS SOAP Header Authentication Basic Authentication (HTTPS Header) IUID REGISTRY APIS PROCUREMENT API ProcurementAPI_OBJ OBJ Request OBJ Response ProcurementAPI_XML XML Request XML Response ProcurementAPI HTTP GET & POST HTTP Request HTTP Response UII VERIFICATION API UIIVerification_OBJ OBJ Request OBJ Response UIIVerification_XML XML Request XML Response UIIVerification HTTP HTTP Request HTTP Response UII VALIDATION API UIIValidation_OBJ... 13

4 IUID API SUM DRAFT VERSION iii OBJ Request OBJ Response UIIValidation_XML XML Request XML Response UIIValidation HTTP HTTP Request HTTP Response WARRANTY API Warranty_OBJ OBJ Request OBJ Response Warranty_XML XML Request XML Response Warranty HTTP HTTP Request HTTP Response UII RETRIEVAL API UIIRetrieval_OBJ OBJ Request OBJ Response UIIRetrieval_XML XML Request XML Response UIIRetrieval HTTP HTTP Request HTTP Response UII RETRIEVAL FROM MARKS API UIIRetrievalFromMarks_OBJ OBJ Request OBJ Response UIIRetrievalFromMarks _XML XML Request XML Response... 35

5 IUID API SUM DRAFT VERSION iv 10.3 UIIRetrievalFromMarks HTTP HTTP Request HTTP Response ELEMENT RETRIEVAL API ElementRetrieval_OBJ OBJ Request OBJ Response ElementRetrieval _XML XML Request XML Response ElementRetrieval HTTP HTTP Request HTTP Response GENERAL (IUIDAPI) API GeneralAPI_OBJ OBJ Request OBJ Response GeneralAPI _XML XML Request XML Response GeneralAPI HTTP HTTP Request HTTP Response List of Tables Table 5-1 API WSDL, Methods and Schema... 4

6 IUID API SUM DRAFT VERSION Scope 1.1 Identification This is the Software User Manual (SUM) for the Item Unique Identification (IUID) Application Programming Interface (API) version System Overview The IUID Registry is a searchable database with controlled access views. In addition to the web interface, there are several dual overloaded APIs available for accessing the database in a systemic manner. These APIs can be used to verify that an entry exists for one or more Unique Item Identifiers (UII), return the UIIs for an Enterprise Identifier and Serial number and optionally Part Number and Batch/Lot, fetch a subset of the pedigree data for a given UII, check warranty information, and validate the UII created by its parts as well as verify that an entry exists for a UII. 1.3 Document Overview This SUM provides information on how to use the IUID Registry API web services. The API is described, and samples are first provided for valid and invalid XML formats. 2.0 Software Summary The following is a summary of the IUID API application and the computer software necessary to use it. 2.1 Software Application The IUID API is a set of Web services provided for building software applications that interface with the IUID registry. There are several APIs in IUID for querying the registry: UII Verification, UII Retrieval from Elements, Element Retrieval from UIIs, UII Validation, UII Retrieval from Mark, and Warranty. An authentication required for using these Web services. 2.2 Security and Privacy Considerations As this is a private and secure API, all communication with the web service will occur over an SSL connection. The user will need to pass in an appropriate account name and password for the request to be processed. 3.0 Authentication Methods 3.1 SOAP Header Authentication For SOAP 1.1 & SOAP 1.2, you need to use soap:header to pass in security information. It uses WS- Security. Please click here for more information on WS-Security Username Token.

7 IUID API SUM DRAFT VERSION Basic Authentication (HTTPS Header) For HTTP GET & POST, you need to use HTTP Authorization Header to pass in security information. This authentication uses BASIC access authentication where you will need pass in User ID and Password as Base64 encoded string. Please click here for more information on BASIC authentication. Username and password are combined into a string "username:password". Please click here to see how to calculate your Base64 for your username:password (don't forget to use colon : to concatenate username and password) 4.0 IUID Registry APIs The IUID Registry provides interfaces that allow software to access selected information. These interfaces are implemented as web services, which take in parameters and return results via XML. While each API request has a different schema, the response for that API is also included in that schema. Within the response XML is a Result Status section. This section says whether or not the XML was successfully processed. If the tag <Success> contains true, the request XML was processed by the IUID Registry, and the requested information provided. If the <Success> tag contains false, there was a problem with the request XML and the IUID Registry data was not accessed. There is a <Message> section that provides more information about the response if a false status is returned. For each of the APIs, there is a schema document as well as a web page where the XML format can be tested prior to system implementation. Table 5-1 provides the URLs and links to the WSDLs, methods and schemas.

8 IUID API SUM DRAFT VERSION 3 API Type Location Procurement API WSDL htttps://wawf.eb.mil/iuidapi/endpoints/procurementservice.wsdl UII Verification API UII Validation API Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST WSDL Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST WSDL Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST htttps://wawf.eb.mil/iuidapi/schemas/procurement.xsd htttps://wawf.eb.mil/iuidapi/endpoints/uiiverificationservice.wsdl htttps://wawf.eb.mil/iuidapi/schemas/uiiverification.xsd htttps://wawf.eb.mil/iuidapi/endpoints/uiivalidationservice.wsdl htttps://wawf.eb.mil/iuidapi/schemas/uiivalidation.xsd Warranty API WSDL htttps://wawf.eb.mil/iuidapi/endpoints/warrantyservice.wsdl General (IUID) API Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST WSDL Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST htttps://wawf.eb.mil/iuidapi/schemas/warranty.xsd htttps://wawf.eb.mil/iuidapi/endpoints/generalpurposeservice.wsdl htttps://wawf.eb.mil/iuidapi/schemas/general.xsd htttps://wawf.eb.mil/iuidapi/schemas/iuidapiin.xsd htttps://wawf.eb.mil/iuidapi/schemas/iuidapiout.xsd UII Retrieval WSDL htttps://wawf.eb.mil/iuidapi/endpoints/retrievalservice.wsdl Schema SOAP 1.1 & SOAP 1.2 htttps://wawf.eb.mil/iuidapi/schemas/uiiretrieval.xsd

9 IUID API SUM DRAFT VERSION 4 UII Retrieval From Marks API Element Retrieval API HTTP GET & POST WSDL Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST WSDL Schema SOAP 1.1 & SOAP 1.2 HTTP GET & POST htttps://wawf.eb.mil/iuidapi/endpoints/retrievalservice.wsdl htttps://wawf.eb.mil/iuidapi/schemas/uiiretrievalfrommark.xsd ML htttps://wawf.eb.mil/iuidapi/endpoints/retrievalservice.wsdl htttps://wawf.eb.mil/iuidapi/schemas/elementretrieval.xsd Table 5-1 API WSDL, Methods and Schema 5.0 Procurement API This API is used to return a list of Contract values that have a given DoDAAC in them. The following web methods are available to this API 1. ProcurementAPI_OBJ: Pass in an array of DoDAACs as an object, and receive a response object. 2. ProcurementAPI_XML: Pass in an XML string, and receive an XML response. XML string is verified against the XML schema. 5.1 ProcurementAPI_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

10 IUID API SUM DRAFT VERSION OBJ Response

11 IUID API SUM DRAFT VERSION ProcurementAPI_XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

12 IUID API SUM DRAFT VERSION XML Response

13 IUID API SUM DRAFT VERSION ProcurementAPI HTTP GET & POST The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request HTTP Response

14 IUID API SUM DRAFT VERSION UII Verification API This API is used to verify whether or not a UII resides in the Registry. One or more UIIs may be provided in a single query. For each UII provided, the API will return a registered or not registered value that lets the submitter know if an item with that UII value has already been registered. To access the UII Verification API, you will need to call one of the methods listed below: 1. UIIVerification_OBJ: Pass in an array of UIIs as an object, and receive a response object. 2. UIIVerification_XML: Pass in an XML string, and receive an XML response. 6.1 UIIVerification_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

15 IUID API SUM DRAFT VERSION OBJ Response

16 IUID API SUM DRAFT VERSION UIIVerification_XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

17 IUID API SUM DRAFT VERSION XML Response 6.3 UIIVerification HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request

18 IUID API SUM DRAFT VERSION HTTP Response 7.0 UII Validation API This API is used to validate the UII construction from its parts and to determine whether or not a UII resides in the registry. One or more UIIs may be provided in a single query. To access the UIIValidation API, you will need to call one of the methods listed below from the UIIValidation web service: 1. UIIValidation_OBJ: Pass in an array of UIIs as an object, and receive a response object. 2. UIIValidation_XML: Pass in an XML string, and receive an XML response. 7.1 UIIValidation_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service.

19 IUID API SUM DRAFT VERSION OBJ Request

20 IUID API SUM DRAFT VERSION OBJ Response 7.2 UIIValidation_XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

21 IUID API SUM DRAFT VERSION 16

22 IUID API SUM DRAFT VERSION XML Response

23 IUID API SUM DRAFT VERSION UIIValidation HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request

24 IUID API SUM DRAFT VERSION HTTP Response

25 IUID API SUM DRAFT VERSION Warranty API To retrieve warranty information for a list of UIIs, you will use the Warranty API. One or more UIIs may be provided in a single query. For each UII provided, the API will return a list of all Warranty Indicators and their associated Warranty Indicator Date, Award Instrument (Contract), and Warranty Event. If the Warranty Event is Rollover the API will also return Rollover Type and the Rollover Value. If the Award Instrument (Contract Number) does not exist the message No contract record will be given. If no warranty information is found for the given UII the message No warranty information reported will be displayed. To access the Warranty API, you will need to call one of the following methods listed below: 1. Warranty_OBJ: Pass in an array of UIIs as an object, and receive a response object. 2. Warranty_XML: Pass in an XML string, and receive an XML response. 8.1 Warranty_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

26 IUID API SUM DRAFT VERSION OBJ Response

27 IUID API SUM DRAFT VERSION Warranty_XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

28 IUID API SUM DRAFT VERSION XML Response

29 IUID API SUM DRAFT VERSION Warranty HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request HTTP Response

30 IUID API SUM DRAFT VERSION UII Retrieval API The UII Retrieval API returns one or more UII if their pedigree elements match all of the elements provided in the XML or pedigree object. The package can contain values for one or more of the elements Enterprise Identifier, Serial Number, Part Number, and Batch/Lot. To access the UII Retrieval API, you will need to call one of these listed below from the retrieval web service: 1. UIIRetrieval_Obj: Pass in an array of pedigree objects as an object, and receive a response object. 2. UIIRetrieval_XML: Pass in an XML string, and receive an XML response. 9.1 UIIRetrieval_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

31 IUID API SUM DRAFT VERSION 26

32 IUID API SUM DRAFT VERSION OBJ Response 9.2 UIIRetrieval_XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

33 IUID API SUM DRAFT VERSION XML Response

34 IUID API SUM DRAFT VERSION 29

35 IUID API SUM DRAFT VERSION UIIRetrieval HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request HTTP Response

36 IUID API SUM DRAFT VERSION 31

37 IUID API SUM DRAFT VERSION UII Retrieval From Marks API To retrieve one or more UIIs by passing in one or more sets of Marks, you will use the UII Retrieval from Marks API. For each Mark set supplied, the API will return any associated UIIs for the given Mark set. A Mark set consists of one or more marks but must contain one of the following values for its Content: 1. HULL NUMBER 2. INTERNAL ASSETT NUMBER 3. PROPERTY CONTROL NUMBER 4. SERIAL NUMBER 5. TAIL NUMBER 6. USA NUMBER 7. ASAF NUMBER 8. USN NUMBER To access the UII Retrieval from Marks API, you will need to call one of the methods listed below from the retrieval web service: 1. UIIRetrievalFromMarks: This is the overloaded method which will accept either an XML formatted string or an array of Mark set objects as an object. If you pass in an XML formatted string, you will receive an XML response. If you pass in an array object, your response will be returned in an object. 2. UIIRetrievalFromMarks_Obj: Pass in an array of Mark set objects, and receive a response object UIIRetrievalFromMarks_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

38 IUID API SUM DRAFT VERSION OBJ Response

39 IUID API SUM DRAFT VERSION UIIRetrievalFromMarks _XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

40 IUID API SUM DRAFT VERSION XML Response

41 IUID API SUM DRAFT VERSION UIIRetrievalFromMarks HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request

42 IUID API SUM DRAFT VERSION HTTP Response

43 IUID API SUM DRAFT VERSION Element Retrieval API This API is used to retrieve a subset of the pedigree data for a UII namely, Enterprise Identifier, Serial Number, Original Part Number, and Batch Lot. One or more UIIs may be provided in each API call. To access the Elements Retrieval API, you will need to call one of the three methods listed below from the retrieval.asmx web service: 1. ElementsRetrieval_Obj: Pass in an array of UIIs as an object, and receive a response object. 2. ElementsRetrieval_XML: Pass in an XML string, and receive an XML response ElementRetrieval_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

44 IUID API SUM DRAFT VERSION OBJ Response

45 IUID API SUM DRAFT VERSION ElementRetrieval _XML The following sample shows a request and response for SOAP 1.1 XML service XML Request XML Response

46 IUID API SUM DRAFT VERSION 41

47 IUID API SUM DRAFT VERSION ElementRetrieval HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request HTTP Response

48 IUID API SUM DRAFT VERSION General (IUIDAPI) API This API is used to return from a subset of data up to all associated data for a list of one or more UII values. The following web methods are available to this API 1. GeneralAPI_Obj: Pass in an array of UII values and specific Boolean properties as an object, and receive a response object. 2. GeneralAPI_XML: Pass in an XML string, and receive an XML response GeneralAPI_OBJ The following sample shows a request and response for SOAP 1.1 OBJ service OBJ Request

49 IUID API SUM DRAFT VERSION OBJ Response

50 IUID API SUM DRAFT VERSION GeneralAPI _XML The following sample shows a request and response for SOAP 1.1 XML service XML Request

51 IUID API SUM DRAFT VERSION 46

52 IUID API SUM DRAFT VERSION XML Response

53 IUID API SUM DRAFT VERSION 48

54 IUID API SUM DRAFT VERSION GeneralAPI HTTP The following sample is based on HTTP GET request. HTTP POST request/response is similar to HTTP GET method HTTP Request

55 IUID API SUM DRAFT VERSION HTTP Response

56 IUID API SUM DRAFT VERSION 51

57 IUID API SUM DRAFT VERSION 52