Gemini and NTS Exit Reform API Usage Guidelines
Total Page：16
File Type：pdf, Size：1020Kb
Gemini and NTS Exit Reform API Usage Guidelines ~ 1 ~ Table of Contents 1. Introduction ............................................................................................................................................6 1.1. API Technology Overview ....................................................................................................................6 2. API Client Development Guidelines .....................................................................................................8 2.1. HTTPS and SSL ...................................................................................................................................9 2.2. Authentication and Authorization ...................................................................................................... 10 2.3. Maintaining the Session .................................................................................................................... 10 2.4. Authentication / Loss of Session / Authorization Failures ................................................................. 10 2.5. Request a Compressed Response to your API Client ...................................................................... 11 3. API Configuration Details ................................................................................................................... 14 3.1. API Technology Overview ................................................................................................................. 14 3.2. Network Requirements ...................................................................................................................... 15 3.3. API Service Connectivity Confirmation ............................................................................................. 15 4. Specifications for Session Management APIs ................................................................................. 15 4.1. Login API ........................................................................................................................................... 16 4.2. Functional APIs ................................................................................................................................. 27 4.3. Logout API ......................................................................................................................................... 29 4.4. Change Password API ...................................................................................................................... 29 5. Error Handling ..................................................................................................................................... 32 5.1. Errors Reported via XML ................................................................................................................... 33 5.2. Error XML Specification .................................................................................................................... 34 5.3. Error Schema Definition .................................................................................................................... 35 5.4. Generic Error Codes ......................................................................................................................... 36 6. Functional API Specifications ........................................................................................................... 38 6.1. API Scope ......................................................................................................................................... 39 6.2. Date Formats ..................................................................................................................................... 43 7. Element Name Abbreviations ............................................................................................................ 44 7.1. Entry Capacity APIs .......................................................................................................................... 44 7.2. Entry Balancing APIs......................................................................................................................... 46 7.3. NTS Exit Capacity APIs .................................................................................................................... 54 8. Debugging for API Client Developers ............................................................................................... 56 ~ 2 ~ 9. Document Control ............................................................................................................................... 57 9.1. Superseded Documents .................................................................................................................... 57 9.2. Version History .................................................................................................................................. 57 ~ 3 ~ List of Figures Figure 1: API Client Communication with Gemini/NTS Exit Reform ..................................................................6 Figure 2: API Client Sequence of Interactions with Gemini / NTS Exit Reforms ................................................10 Figure 3: Interaction between Web Client and Web Server ............................................................................ 23 Figure 4: Interaction between Web Client and Web Server involving a redirection of 3xx status code ........... 24 Figure 5: Example Logic for Determining the Cause of Authentication/Loss of Session/ Authorization Failures .................................................................................................................................................................. 28 Figure 6: Error Handling by Severity of Error .................................................................................................. 34 List of Tables Table 1: Authentication / Loss of Session / Authorization Failures ................................................................. 13 Table 2: Password and Session Policies ......................................................................................................... 15 Table 3: Login API Request Headers .............................................................................................................. 19 Table 4: Login API Response Headers - Successful Authentication/ Authorization ....................................... 20 Table 5: Authentication/Authorization Failed ................................................................................................... 21 Table 6: Redirection Scenarios ....................................................................................................................... 26 Table 7: Scenarios not Involving a Redirection ............................................................................................... 27 Table 8: Functional API Request Headers ...................................................................................................... 29 Table 9: Functional API Request Body............................................................................................................ 30 Table 10: Functional API Response Headers ................................................................................................. 30 Table 11: HTTPS Request Headers ................................................................................................................ 31 Table 12: Change Password API Request Parameters .................................................................................. 32 Table 13: Change Password API Response Codes ........................................................................................ 33 Table 14: Error Scenarios for Query APIs ....................................................................................................... 35 Table 15: Error Scenarios for Update APIs ..................................................................................................... 36 Table 16: Error XML Specification ................................................................................................................... 36 Table 17: Generic API Error Codes ................................................................................................................. 38 Table 18: Entry Capacity ................................................................................................................................. 41 Table 19: Energy Balancing ............................................................................................................................ 41 Table 20: NTS Exit Capacity Functional APIs ................................................................................................. 43 Table 21: Entry Capacity APIs ......................................................................................................................... 44 Table 22: Energy Balancing APIs .................................................................................................................... 46 Table 23: NTS Exit Capacity APIs ................................................................................................................... 54 ~ 4 ~ List of Abbreviations Acronym Description API Application Programming Interface DOM Document Object Model BA Business Associate HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol Secure IX Information Exchange LSO Local Security Officer NG National Grid NTS National Transmission System SAX