{"type":"doc","content":[{"type":"paragraph"},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"_parentId":{"value":"744587380"}},"macroMetadata":{"macroId":{"value":"b43bfd98-5514-43e9-a1d2-dd31631a512c"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"4da0f01e-c682-41cb-9bdf-363dd8d3a81c"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"About the REST API","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"The Jiwa 8 REST API is a restful web service providing a means to interact with the Jiwa database and business logic via HTTP verbs.","type":"text"}]},{"type":"paragraph","content":[{"text":"The bulk of the REST API is provided by a Jiwa plugin. A windows service and web deployment package provide the mechanism to host the service, but the routes and the logic behind each route are defined in the plugin. Additional or alternative routes and logic can be provided by an additional plugin or plugins. See ","type":"text"},{"text":"Adding Custom Routes to the REST API","type":"text","marks":[{"type":"link","attrs":{"__confluenceMetadata":{"spaceKey":"J7UG","isRenamedTitle":true,"linkType":"page","contentTitle":"Adding Custom Routes to the REST API","versionAtSave":"66"},"href":"https://jiwa.atlassian.net/wiki/spaces/J7UG/pages/987123"}}]},{"text":" for information on this.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Jiwa 8 REST API uses the ","type":"text"},{"text":"ServiceStack","type":"text","marks":[{"type":"link","attrs":{"href":"https://servicestack.net/"}}]},{"text":" framework. It produces not only a pure HTTP web service, accessible by any HTTP-capable client, but also has support for ","type":"text"},{"text":"strongly typed clients","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/clients-overview#servicestack-clients"}}]},{"text":":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"C# Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/csharp-client"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TypeScript Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/typescript-add-servicestack-reference"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java/Kotlin Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/java-add-servicestack-reference"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Swift Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/swift-add-servicestack-reference"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Silverlight Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/silverlight-client"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JavaScript Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/javascript-client"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Dart Client","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/dart-client"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MQ Clients","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.servicestack.net/redis-mq"}}]}]}]}]},{"type":"paragraph","content":[{"text":" You don't need to use a ServiceStack client to consume the REST API - as it is a pure HTTP REST service - but the ServiceStack clients bring the benefit of smaller, cleaner code and strong typing such that many mistakes are caught at compile time rather than runtime.","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Minimum Requirements","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"The REST API requires SQL Server 2012 or later and Jiwa 8.0.14 or later.","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Use Cases","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Typical use cases for the REST API Are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Integrate a web store to Jiwa","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Field sales via a mobile device (iOS/Android/UWA)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Integrate Jiwa and Point Of Sale systems","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Provide intranet services to staff via a web browser","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Provide specialised browser based interfaces for tailored, streamlined operational workflows.","type":"text"}]}]}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Deployment and Configuration","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"The first step to installation is to enable the REST API plugin in Jiwa.","type":"text"}]},{"type":"paragraph","content":[{"text":"Open the Plugin Maintenance form, locate the REST API plugin and check the \"Enabled\" checkbox, then press the save button on the ribbon. Exit Jiwa and log back in, and then open the System configuration form.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three system settings introduced by the plugin:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileSize":30775,"__fileMimeType":"image/png","width":1238,"id":"04b4b948-b31b-43cb-a792-e5c49d26909c","collection":"contentId-744587380","type":"file","__fileName":"REST API - System Configuration.PNG","height":293}}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"SessionExpiryInMinutes","type":"text","marks":[{"type":"strong"}]},{"text":" specifies how many minutes elapse since the last API call was received before expiring the session and logging the user out.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"DebugMode ","type":"text","marks":[{"type":"strong"}]},{"text":"indicates if stack traces are to be returned in error responses, and if requests should be logged.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"AutoQueryMaxLimit","type":"text","marks":[{"type":"strong"}]},{"text":" limits the number of rows that can be returned by an auto query - this is good for preventing inadvertent denial-of-service (dos) through a wayward query.","type":"text"}]},{"type":"paragraph","content":[{"text":"Jiwa must be installed on the machine to host the service.","type":"text"}]},{"type":"paragraph","content":[{"text":"Locate the Jiwa Financials program folder (%Program Files%/Jiwa Financials/Jiwa) and edit the JiwaAPISelfHostedService.exe.config file. The default configuration looks like the following:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Default Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\t \n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The appSettings section has the value which will need to be edited. Change the value attribute contents for each of the keys ServerName, DatabaseName, Jiwausername, JiwaPassword and URLBase. The keys are explained in the following table.","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":1800.0,"localId":"581bfcbc-c193-4edb-b317-c217136bac11"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Key","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"ServerName","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The name of the SQL Server","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"DatabaseName","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The database name","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"JiwaUsername","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The Jiwa user for the service to initially connect to. The service will use this username to connect to Jiwa once at service start, and it then disconnects.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"JiwaPassword ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The password for the user","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"URLBase","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The base url. The default value of ","type":"text"},{"text":"http://*:80/","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":" indicates all site names running on the local machine, on port 80 will work. So ","type":"text"},{"text":"http://localhost","type":"text","marks":[{"type":"link","attrs":{"href":"http://localhost/"}}]},{"text":" for use within the firewall, and if a port forward is configured then any port 80 traffic will be accepted. To restrict to a specific domain replace the * with the domain name - for example: ","type":"text"},{"text":"http://example.com:80/","type":"text","marks":[{"type":"link","attrs":{"href":"http://example.com/"}}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The trailing forward slash is important! Make sure your URLBase ends with a /","type":"text"}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Ensure that there are no other services (i.e. a local web-server such as IIS) already listening on the port you choose, otherwise the Windows services will error upon starting.","type":"text"}]}]},{"type":"paragraph"}]}]}]},{"type":"paragraph","content":[{"text":"Now open services.msc and edit the properties of the Jiwa 8 Self Hosted REST API service - right click on the service and select \"Properties\" from the context menu:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":890,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileSize":76518,"__fileMimeType":"image/png","width":694,"id":"b159d33d-4e44-4e85-a487-e97237de9afa","collection":"contentId-744587380","type":"file","__fileName":"image2017-2-17 11:28:5.png","height":546}}]},{"type":"paragraph","content":[{"text":"On the ","type":"text"},{"text":"General","type":"text","marks":[{"type":"strong"}]},{"text":" tab, change the ","type":"text"},{"text":"Startup Type","type":"text","marks":[{"type":"strong"}]},{"text":" to be Automatic (Delayed Start)","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":607,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileSize":14507,"__fileMimeType":"image/png","width":406,"id":"f8a3d538-0277-4d03-b6ba-7fb2fa5bb362","collection":"contentId-744587380","type":"file","__fileName":"RESTAPI_Service_Properties_General.png","height":468}}]},{"type":"paragraph","content":[{"text":"On the ","type":"text"},{"text":"Log On","type":"text","marks":[{"type":"strong"}]},{"text":" tab, select ","type":"text"},{"text":"Log on as","type":"text","marks":[{"type":"strong"}]},{"text":" to be the ","type":"text"},{"text":"Local System account","type":"text","marks":[{"type":"strong"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":607,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileSize":16056,"__fileMimeType":"image/png","width":406,"id":"27e79e04-7330-4626-a418-560540eb92d4","collection":"contentId-744587380","type":"file","__fileName":"image2017-2-17 11:38:8.png","height":468}}]},{"type":"paragraph","content":[{"text":"On the ","type":"text"},{"text":"Recovery","type":"text","marks":[{"type":"strong"}]},{"text":" tab, change the ","type":"text"},{"text":"First","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Second","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"Subsequent failures","type":"text","marks":[{"type":"strong"}]},{"text":" to be \"","type":"text"},{"text":"Restart the Service","type":"text","marks":[{"type":"strong"}]},{"text":"\".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":607,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileSize":26903,"__fileMimeType":"image/png","width":406,"id":"044b30f9-b638-400c-b13b-7ca8e7f1f494","collection":"contentId-744587380","type":"file","__fileName":"image2017-2-17 11:39:24.png","height":468}}]},{"type":"paragraph","content":[{"text":"Press Apply and then back on the ","type":"text"},{"text":"General","type":"text","marks":[{"type":"strong"}]},{"text":" tab press the ","type":"text"},{"text":"Start","type":"text","marks":[{"type":"strong"}]},{"text":" button. If the service fails to start, check the event log for any information relating to the service.","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"You can then check to see if the service is working by opening a browser and entering \"localhost\" in the address bar.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":1052,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileSize":55289,"__fileMimeType":"image/png","width":649,"id":"e0bbfb5c-9332-4db2-8f1d-491d29ef985d","collection":"contentId-744587380","type":"file","__fileName":"image2017-2-17 11:43:5.png","height":432}}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Setting Route Permissions"},"legacyAnchorId":{"value":"RESTAPI-SettingRoutePermissions"},"_parentId":{"value":"744587380"}},"macroMetadata":{"macroId":{"value":"adfe18e7-6508-4781-940e-f65c0137d19a"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"e99ec6ca-6c79-4a5b-b2d7-0e6a91b637fc"}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Setting Route Permissions","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Once the service is running, permissions must be set within Jiwa to specify which user groups can access which routes. This is done via the User Group Maintenance form in Jiwa.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Load the User Group Maintenance form","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":1424,"widthType":"pixel"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":1131,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":556}}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Default REST API Permission","type":"text"}]},{"type":"paragraph","content":[{"text":"In the Group Information section of the form, there is a field labelled \"Default REST API Permission\". This can be one of 3 values - Undefined, Allow or Disallow.","type":"text"}]},{"type":"paragraph","content":[{"text":"When set to Disallow, all users belonging to that user group will not be able to invoke any route, regardless of other permissions","type":"text"}]},{"type":"paragraph","content":[{"text":"When set to Allow, users belonging to that user group will be able to invoke any route - provided they are not a member of another group which disallows, or an explicit route permission is set to disallow.","type":"text"}]},{"type":"paragraph","content":[{"text":"When set to Undefined, users belonging to that user group will be unable to invoke any route - unless they are a member of another group which allows, or an explicit route permission is set to allow, and belong to no groups where the default or route permission is disallow.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Explicit Route / Path Permission","type":"text"}]},{"type":"paragraph","content":[{"text":"Explicit permissions per route can be made for a User Group. In the \"Import Path\" field of the REST API tab of User Group Maintenance, enter the URL of the REST API followed by /RestPaths and press the Import button. This will visit the REST API and retrieve a list of all routes:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":954,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":321}}]},{"type":"paragraph","content":[{"text":"Then permissions can be set per route.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Adding Custom Routes","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Adding Custom Routes to the REST API","type":"text","marks":[{"type":"link","attrs":{"__confluenceMetadata":{"spaceKey":"J7UG","isRenamedTitle":true,"linkType":"page","contentTitle":"Adding Custom Routes to the REST API","versionAtSave":"66"},"href":"https://jiwa.atlassian.net/wiki/spaces/J7UG/pages/987123"}}]},{"text":" for information on how to extend the REST API to add your own custom routes.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Testing the API","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Once you have the REST API running, it can quickly be tested using the SwaggerUI which is deployed by default. This is a browser interface for calling the routes.","type":"text"}]},{"type":"paragraph","content":[{"text":"When you open a browser to the location of your api, it by default opens on the metadata page. At the bottom of this are some links - one of them is a link to the the Swagger UI","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":541,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":600}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Clicking on the Swagger UI link will take you to the Swagger UI, built on the Open API specification document.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":969,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":625}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Most operations require authentication, so click on the auth group to expand it:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":984,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":422}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Then click on the /auth route to expand that:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":750,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":657}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Scroll down to the Parameters and fill out the UserName and Password fields:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":543,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":251}}]},{"type":"paragraph","content":[{"text":"Then scroll down and press the \"Try it Out!\" button. You should see a response come back:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":726,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":689}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Now that you are authenticated, you can visit other routes - for example to retrieve a list of products, visit the /Inventory route and use the GET method:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":897,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":505}}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Securing the API","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Best practices for securing your API are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Turn off Debug Mode system setting. Leaving this on logs to request logs all requests - including credentials - and exposes a route to query and inspect the logs.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If using the Self Hosted service, don't run as a Windows Administrator account. Create a dedicated Windows User to run as.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't set allow permissions on every route - only permit what is needed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If giving customers access to your API, give them Debtor API Keys and not Staff API Keys.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't use a privileged Jiwa user account for API Keys (don't give admin users API keys).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use an auto-renewing SSL Certificate. Lets Encrypt is a free service which can be used to generate, install and renew SSL certificates.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you do not need to publicly expose your API, then don't.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you do need to publicly expose your API, consider a whitelisted IP address access policy - for instance if your API is only ever accessed by a web store, then whitelist the IP of that web store.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Consider using a front-end proxy such as Cloudflare. Services such as Cloudflare can filter out malicious traffic before it reaches your API.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Consider employing rate limiting. The optional plugin REST API Rate Limit can be used to set limits on how often an IP address can call the API in a configurable time interval.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SSL Certificates","type":"text"}]},{"type":"paragraph","content":[{"text":"Recommended practice is to use an SSL certificate for all http traffic, so the environment should be configured such that the Jiwa REST API also uses SSL.","type":"text"}]},{"type":"paragraph","content":[{"text":"When using the Jiwa self hosted REST API service, it is a Windows environment configuration to install and bind the certificate. Once the environment is configured for SSL, all that is needed for the Jiwa configuration is to use the https prefix and correct hostname and port for the URLBase configuration setting in the JiwaAPISelfHostedService.exe.config.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":749,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":524}}]},{"type":"paragraph","content":[{"text":"Tools such as the free ","type":"text"},{"text":"Win-Acme","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.win-acme.com/"}}]},{"text":" client can be used to generate, install and renew automatically certificates using the Lets Encrypt service, and these tools will also add the binding necessary for the certificate. If using IIS, then the IIS Manager should be used to bind a certificate to the hostname and port.","type":"text"}]},{"type":"paragraph","content":[{"text":"To view which certificates are installed, you can use certlm.msc (the Local Machine Certificate Manager).","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":999,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":565}}]},{"type":"paragraph","content":[{"text":"Typically certificates will be found in the Personal (MY) store.","type":"text"}]},{"type":"paragraph","content":[{"text":"The certificate must be a valid, current (not expired) certificate, or else clients consuming the API will likely refuse or drop the connection.","type":"text"}]},{"type":"paragraph","content":[{"text":"To view the bindings for the certificates, use an elevated command prompt (run as Administrator) and the following command:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"netsh http show sslcert","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":643,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":531}}]},{"type":"paragraph","content":[{"text":"If the binding desired is not present, add one with the following command:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"netsh http add sslcert hostnameport=api.jiwa.com.au:443 certhash=4a3b19ddaa7956fb511aebc9feaa28ab4ff6d0ee appid={91c8a897-2234-46a7-8adc-ace477f87e54} certstorename=MY","type":"text"}]},{"type":"paragraph","content":[{"text":"Obviously you would change the hostname, port, certhash and certstore name to suit your own environment.","type":"text"}]},{"type":"paragraph","content":[{"text":"The certhash is the Certificate Hash and can be obtained from the netsh command to view certificates, or by double-clicking the certificate in the certlm.msc to open the Certificate dialog and locating the Thumbprint property of the Details tab.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":1002,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":567}}]},{"type":"paragraph","content":[{"text":"If you find there is a binding which you want to remove (perhaps an expired certificate), then you can do that with:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"netsh http del sslcert hostnameport=api.jiwa.com.au:443","type":"text"}]},{"type":"paragraph","content":[{"text":"Again, substitute the appropriate values with your own.","type":"text"}]},{"type":"paragraph","content":[{"text":"Depending on your DNS configuration, you may also wish to edit the Hosts file on the machine running the REST API service, so that the DNS name for the API resolves to the local machine. This will allow the FQDN to be accessible on the machine running the REST API service - which may be useful in debugging or testing. The hosts file is found in the C:\\Windows\\System32\\drivers\\etc folder.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"full-width"},"content":[{"type":"media","attrs":{"__fileMimeType":"application/octet-stream","width":943,"id":"UNKNOWN_MEDIA_ID","collection":"","type":"file","height":501}}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"API Troubleshooting Checklist","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"In resolving problem with the API some of the basic things that can be checked are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Can you log into Jiwa as the user the api trying to use on the actual server and were there any error messages when you did?","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This is because the user being used by the API must log onto Jiwa just as any normal user would and if an error occurs at login that could also cause a problem with the API.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Verify the version of the REST api plugin loaded into the database matches the one in JiwaAPI.zip in the Jiwa program directory that the api is running from.","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This is because every service release of Jiwa comes with an updated version of the REST api that can be located in this zip file and the release has only be tested against this version of the plugin.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Has the Windows event log been checked to see if any plugins have failed to compile, the Jiwa REST API will report any error there?","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This is because when plugins are checked at login, any differences will cause Jiwa to recompile that plugin which involves writing files to disk which could result in an error.","type":"text"},{"type":"hardBreak"},{"text":" ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"What error message is being produced in terms of the HTTP status code returned and the error message from the body of the response?","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This is because the API can produce an error for a variety of reasons, including things like it doesn’t understand the data being sent to it, or it is being asked to retrieve data that is not in its database, not only will the Http status code have significance about the error but quite often the body of the response will include text about what the problem was such as product not found. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Has performing the same steps been tried against a Jiwa Demo Database and did this produce any errors?","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This is because errors can be environmental in terms of they can be related to the operating system environment or database specific where given code in other plugins or data could be causing an issue. When testing against a Jiwa Demo database doesn’t produce the same errors, one good starting point is to look at what plugins are enabled in the problem database compared to the Jiwa Demo database. ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related articles","type":"text"}]},{"type":"paragraph","content":[{"type":"placeholder","attrs":{"text":"Related articles appear here based on the labels you select. Click to edit the macro and add or change labels."}}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"contentbylabel","parameters":{"macroParams":{"showLabels":{"value":"false"},"_parentId":{"value":"744587380"},"max":{"value":"5"},"spaces":{"value":"API"},"showSpace":{"value":"false"},"sort":{"value":"modified"},"type":{"value":"page"},"reverse":{"value":"true"},"labels":{"value":"consume c-sharp"},"cql":{"value":"label = \"restapi\" and type = \"page\" and space = \"J7UG\""}},"macroMetadata":{"macroId":{"value":"65fd37ef-037f-4b31-b8f1-ebeb30b91fa3"},"schemaVersion":{"value":"4"},"title":"Filter by label"}},"localId":"663af44d-51c8-498f-86cc-05b75511c633"}},{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"details","parameters":{"macroParams":{"hidden":{"value":"true"},"_parentId":{"value":"744587380"}},"macroMetadata":{"macroId":{"value":"769d7480-d964-4434-823a-78fe4efda811"},"schemaVersion":{"value":"1"},"title":"Page Properties"}},"localId":"10bbde5d-863f-4a47-bd17-bde034346252"},"content":[{"type":"paragraph"},{"type":"table","attrs":{"layout":"default","localId":"cd10cc1f-454d-448b-b87e-b5877067808f"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Related issues","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph"}]}]}]},{"type":"paragraph"}]},{"type":"paragraph"}],"version":1}

Browser not supported