User Tools

Site Tools


webapi_swagger_documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
webapi_swagger_documentation [2017/08/09 10:05]
drogall
webapi_swagger_documentation [2018/11/14 16:14] (current)
kevin [Summary]
Line 1: Line 1:
-====== Windward Web API Swagger Documentation Usage ======+====== Windward Web API Swagger ​2.0 Documentation Usage ======
  
 +===== Summary =====
 +Our Web API solution runs as a service and provides a doorway to push and pull information from a System Five database. ​ This technology will work with both onPrem installations and our System Five on Cloud deployments.  ​
  
 +The following is an explanation for retrieving and using the Swagger 2.0 documentation from all available endpoints of the Windward Web API.
  
 +===== Endpoints =====
  
-===== Summary =====+As of the 6.2.2.175 there are multiple endpoints available for the Windward Web API each providing different functions for the Web API. These endpoints are the following:​ 
 +  - APBill 
 +  - Category 
 +  - Customer 
 +  - Inventory 
 +  - Invoice 
 +  - Keyword 
 +  - Units 
 +  - Vendors 
 +  - VirtualInventory 
 +  - TServerMethodsWebAPI
  
-The following ​is an explanation for retrieving and using the Swagger 2.0 Documentation from the Windward ​Web API.+All of these endpoints can be accessed with either of the following ​URLs: 
 +  * http://​API_IP_ADDRESS:​API_PORT/​Windward/​WebAPI/​ENDPOINT 
 +  * http://​API_IP_ADDRESS:​API_PORT/​datasnap/​rest/​ENDPOINT
  
-*PREREQUISITE* You must have the Web API installed and running properly+==== Deprecated Methods ====
  
-====== Retrieve ​the Documentation ======+As of the 6.2.2.175 the following methods in the endpoint TServerMethodsWebAPI are deprecated. ​ They will continue to operate but with this any new software development should use these methods. 
 +  - Customers_Insert 
 +  - Customer_Read 
 +  - Customers_Update 
 +  - Get_Customers 
 +  - List_Customers 
 +  - Parts_Read 
 +  - Parts_Update 
 +  - Get_Parts 
 +  - List_Parts 
 +  - Insert_Parts 
 +  - Get_Main_Categories 
 +  - Get_Categories 
 +  - Suppliers_Insert 
 +  - Suppliers_Read 
 +  - Suppliers_Update 
 +  - Get_Suppliers 
 +  - List_Suppliers 
 +  - Invoices_Insert 
 +  - Invoices_Get 
 +  - Invoices_Update 
 +  - Invoices_Read 
 +  - Insert_Full_Invoice 
 +  - Insert_AP_Bill
  
-  - The Swagger documentation is retrieved using a method of the Web API Using your preferred method or app (we suggest [[https://​www.getpostman.com|Postman]]),​ send a GET request to the following URL: +Replacement methods for these newly deprecated methods can be found within ​the other endpoints.
-    - http://​webapi_ip_address:​webapi_port/​datasnap/​rest/​TServerMethodsWebAPI/​swagger/​swagger.json +
-  - Save the contents of the response, which is the Swagger documentation +
-  - Use your preferred Swagger editor (we suggest [[http://​editor2.swagger.io|editor2.swagger.io]]) to view the Swagger docs+
  
-===== Example Using Postman ​=====+===== Known Limitations ​=====
  
-  - Open Postman +Prior to 6.2.2.175 released versions of the Web API has a maximum limit of 32 concurrent connectionsThis limit has been removed in the 6.2.2.175 ​and is now limited by how much available memory is on the server or workstation running ​the API.
-  - Set the request type to GET +
-  - Enter the URL, substituting the webapi_ip_address and webapi_port placeholders with the appropriate information for your Web API installation:​ http://​webapi_ip_address:​webapi_port/​datasnap/​rest/​TServerMethodsWebAPI/​swagger/​swagger.json  +
-  - Set the authorization type to Basic and enter your Web API credentials +
-  - Send the request +
-  - Copy the complete text in the Response area and save it as a text file+
  
-====== Example using editor2.swagger.io ======+<note tip> 
 +Due to the JSON parser that the Windward Web API uses, any '​%'​ characters inside of JSON strings will cause internal server errors. 
 +</​note>​
  
 +===== Retrieving The Documentation =====
 +
 +The Swagger documentation for a particular endpoint can be retrieved by using a method of the endpoint. ​ Using your preferred method or app (we suggest [[https://​www.getpostman.com|Postman]]),​ send a GET request to one of the following URLs:
 +    * http://​API_IP_ADDRESS:​API_PORT/​Windward/​WebAPI/​ENDPOINT/​Swagger
 +    * http://​API_IP_ADDRESS:​API_PORT/​datasnap/​rest/​ENDPOINT/​Swagger
 +
 +The contents of the response from the calls is the Swagger 2.0 documentation,​ after copying the response text and saving it into a text file use your preferred Swagger editor (we suggest [[http://​editor.swagger.io|editor.swagger.io]]) to view the Swagger documentation.
 +
 +After configuring your S5WebAPISvc.ini,​ you can view and interact with the Swagger 2.0 documentation and the Web API through a browser, without using Postman or a Swagger editor.
 +
 +==== Getting The Swagger 2.0 Documentation Using Postman ====
 +
 +  - Open Postman.
 +  - Set the request type to GET.
 +  - Enter one of the URLs, substituting the API_IP_ADDRESS,​ API_PORT and ENDPOINT placeholders with the appropriate information for your Web API installation:​
 +    * http://​API_IP_ADDRESS:​API_PORT/​Windward/​WebAPI/​ENDPOINT/​Swagger
 +    * http://​API_IP_ADDRESS:​API_PORT/​datasnap/​rest/​ENDPOINT/​Swagger ​
 +  - Set the authorization type to Basic and enter your Web API credentials.
 +  - Send the request.
 +  - Copy the complete text in the Response area and save it as a text file.
 +
 +==== Getting The Swagger 2.0 Documentation Into editor.swagger.io ====
 +  - Open the json file in a text editor and copy the contents to your clipboard
   - Open a web browser (Google Chrome, for example) and navigate to the following URL:   - Open a web browser (Google Chrome, for example) and navigate to the following URL:
-    - [[http://editor2.swagger.io|editor2.swagger.io]] +      * [[http://editor.swagger.io|editor.swagger.io]] 
-  - Click on the '​File'​ menu +  - Click on the '​File'​ menu. 
-  - Click on 'Paste JSON'​ +  - Click on 'Paste JSON'. 
-  - Paste in the Swagger ​docs text retrieved in the previous step +  - In the Swagger ​2.0 documentation dialog Right click and choose Paste from your clipboard 
-  - Click on '​Import'​ +  - Click on '​Import' ​button. 
-  - The list of available methods ​is now listed on the right side of the screen. ​ Each method has a Parameters and Response section ​that outlines ​the format ​of both the request parameters and the response.+  - The list of available methods ​are now listed on the right side of the screen. ​ Each method has two sections, ​a Parameters and Response section, these sections outline ​the format ​for both the request parameters and the response. 
 +{{:​swagger_io_json.jpg?​400|}} 
 + 
 + 
 +==== Interacting With The Swagger 2.0 Documentation Via A Browser ==== 
 +  - As of Beta 6.2.7, The Swagger 2.0 documentation can be viewed and interacted with through a browser. 
 +  - Using a set of options in the S5WebAPISvc.ini file, the configuration of the Swagger publishing can be set and changed. 
 +    - {{:​undefined:​swagger_ini_options.png?​200|}}  
 +  - Once the S5WebAPISvc.ini options have been set, and the WebAPI service is running, open a web browser and enter localhost:​PORT/​index.html into the address bar 
 +    - Where PORT is the port under the Swagger Publishing options in S5WebAPISvc.ini 
 +  - After entering the WebAPI credentials and clicking the '​Submit'​ button, the swagger-ui page will be shown. 
 +  - On this page, edit the contents of the search/​explore bar. Changing the values for PORT, and ENDPOINT 
 +    - PORT is the port that the WebAPI is listening on (specified in S5WebAPISvc.ini,​ under the HTTP/HTTPS option) 
 +    - ENDPOINT is any one of the endpoints of the WebAPI. 
 +  - After clicking on the '​Explore'​ button and waiting for the Swagger 2.0 documentation to load, click on the '​Authorize'​ button and reenter the WebAPI credentials,​ this must be done before being able to call any of the endpoint'​s methods. 
 +  - Once authorized the Swagger 2.0 documentation and WebAPI service can be interacted with. 
 +    - By clicking on an API method, the page will show more information for the method. 
 +    - Clicking the 'Try It Out' button allows users to enter parameters, and run the method. 
 +    - Clicking the '​Execute'​ button will send the method and it's parameters (if any) to the API, giving back the API'​s ​response. ​
  
webapi_swagger_documentation.1502298336.txt.gz · Last modified: 2017/08/09 10:05 by drogall