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/07/27 15:13] (current)
gking_windwardsoftware.com Added deprecated methods list, and '%' problem in known limitations
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.
  
 +<note important>​You must have the Windward Web API installed and running properly before you are able to retrieve and use the Swagger 2.0 documentation.</​note>​
  
-===== Summary ​=====+===== Endpoints ​=====
  
-The following is an explanation for retrieving and using the Swagger ​2.0 Documentation from the Windward Web API.+As of the 6.2.7 Beta 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
  
-*PREREQUISITEYou must have the Web API installed and running properly+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
  
-====== Retrieve the Documentation ======+==== Deprecated Methods ​====
  
-  - 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+As of the 6.2.7 Beta the following ​methods in the endpoint TServerMethodsWebAPI were deprecated
-    http://​webapi_ip_address:​webapi_port/​datasnap/​rest/​TServerMethodsWebAPI/​swagger/​swagger.json +  Customers_Insert 
-  - Save the contents of the response, which is the Swagger documentation +  - Customer_Read 
-  - Use your preferred Swagger editor (we suggest [[http://​editor2.swagger.io|editor2.swagger.io]]) to view the Swagger docs+  - 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
  
-===== Example Using Postman =====+Replacement methods for these newly deprecated methods can be found within the other endpoints.
  
-  - Open Postman +===== Known Limitations =====
-  - 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 ======+The 6.2.2 released versions of the Web API has a maximum limit of 32 concurrent connections. This limit has been removed in the 6.2.7 beta version and is now limited by how much available memory is on the server or workstation running the API.
  
 +Due to the JSON parser that the Windward Web API uses, any '​%'​ characters inside of JSON strings will cause internal server errors.
 +
 +===== 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://​editor2.swagger.io|editor2.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 editor2.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://​editor2.swagger.io|editor2.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