API Getting Started



PurposeThis documents describes in whole how the Supplier API of Ejendomstorvet works and how to implement it to your code. The document is meant as an introduction which describes how to successfully achieve the first request and what is required of the clientContents TOC \o "1-3" \h \z \u Purpose PAGEREF _Toc97812313 \h 1HAWK authetication api.ejendomstorvet.dk PAGEREF _Toc97812314 \h 2Storage of secret key PAGEREF _Toc97812315 \h 2Time syncing PAGEREF _Toc97812316 \h 2Cross site scripting PAGEREF _Toc97812317 \h 2Calculating the mac PAGEREF _Toc97812318 \h 2Example PAGEREF _Toc97812319 \h 3Errorhandling PAGEREF _Toc97812320 \h 3HTTP status 400 – Bad request PAGEREF _Toc97812321 \h 3HTTP status 500 – Internal server error PAGEREF _Toc97812322 \h 3Compression PAGEREF _Toc97812323 \h 4Caching PAGEREF _Toc97812324 \h 4HTTP Method override PAGEREF _Toc97812325 \h 4API documentation PAGEREF _Toc97812326 \h 4API test PAGEREF _Toc97812327 \h 4API Id, passwords and security keys PAGEREF _Toc97812328 \h 5Older technologies (ASP Classic) PAGEREF _Toc97812329 \h 5OAUTH authetication api.ejendomstorvet.dk PAGEREF _Toc97812330 \h 5HAWK authetication api.ejendomstorvet.dkThe Hawk protocol is used as the main layer of security. Hawk is a protocol which, before every request, a header with a mac is calculated in order to complete any request (with the exception of a request to get the server time).This mac is calculated on the basis of the handed out ID, secret key, destination URL, time and type of request (GET, PUT, POST etc)Every calculated header can be used for 5 minutes before it expires.Storage of secret keyIt is important that the handed out key is stored correctly. Places in source where the key is written is to be protected with the available tools of the chosen platform, for instance machine encrypted .config-files.If the key is stored as plain text, the key should at least then be split up in pieces in order to obscure it, in a case of disassemblement of the binaries.Time syncingAs Hawk is based around the fact that both client and server somewhat agree on the current time, it is important to ensure implementation of this fact. If the client-side is deployed on a server, a time service can be used to ensure that the correct time is always up to date.If the client on the other hand is mobile, it should be taken into consideration that the time on the client’s device is incorrect or is is changed while the application is running.The API has a system/status request which is both used to see if the service is online and what the server-side time is. This is the only request that can be done anonymously.Recommended request sequence:Get the time from system/statusCalculate the timespan between local UTC time and serverCalculate mac for the hawk headerExecute the requestStart at point 3 for the following request. In the case of http status 401 or no response, go to point 1Cross site scriptingThe API does not support cross site scripting (XSS).Calculating the macThe Hawk protocol is described here: in use:HawkNet version 1.4.2.0HawkNet.WebApi version 1.4.4.0The following is always true:SHA-256 encryption is usedMAC headers expire after 5 minutesPayload hashing is not used via Hawk, but the traffic is encrypted through SSL.There exists a couple of implementations of the Hawk algorithm on different platforms. On the server side, we are using HawkNet.The platforms have not all been tested and it is the suppliers’ responsibility to either write the code themselves, or find a standard implementation for their platform.Known platforms: (not complete)HawkNet, a .NET platformThinktecture Identity model Hawk .net platformTent hawk-rubyMohawk python platformWealdtech hawk Java platformExampleThe following example is written in C# .NET, but without the usage of classes and other linquistic specific features to show a more linear code. A real implementation would of course be different.Code to generate Hawk header: code: Api Call example: application is a .NET console application which request the service with a get request.ErrorhandlingThe Web-API contains the following methods for error handling. Each error is handled, based around the returned http status.HTTP status 400 – Bad requestThis error triggers when the request is invalid, for instance if any parameters are missing or the body is incorrect.The returned result object is always a ValidatedResult and is modelled like this:ValidatedResult {ErrorCode (integer, optional): Overall error code,ErrorMessage (string, optional): Overall error message,Items (Array[ValidatedItem], optional): Detailed error items}ValidatedItem {FieldName (string, optional): Optional fieldname for the error,ErrorCode (integer, optional): Optional errorcode for the error,ErrorMessage (string, optional): Message for the error}HTTP status 500 – Internal server errorFejlen kommer ved alvorlige fejl og b?r ikke forekomme med mindre klienten eller serveren har en fejl.{ExceptionType (string): Type name of the exception,ExceptionMessage (string): Error message in the exception,MessageDetail (string): Where to get further details about the error,DetailId (string): Id for detail reference,ErrorCode (string, optional): Categorised error code}CompressionThe API supports standard gzip and deflate compression. To use compression, the AcceptEncoding in the header be set to gzip or deflate.When the response is returned, the compression is indicated in the response as gzip, deflate or identity(none)The response indicates a possible compression in Content-Encoding. Note: Responses below 1kb in size is never compressed.CachingA simple form of cahcing is implemented to save bandwidth.Ordinary ETag caching may be used. All returned responses a marked with an ETag header which can be used for the next requests.The next requests have attached If-None-Match to the header with the saved ETag value from last request. If the server’s response-content contains the same ETag, the response will be HTTP Status 304 (Not modified) and content from the earlier request is used.Note: the server handles requests and calculations even when responding with 304. The request can, as usually with ETag caching, only be used with GET and HEAD requestsHTTP Method overrideOn platforms that use nothing other than standard HTTP method, the HTTP method can be set with the header X-http-Method-Override. Using this method the header can be set to DELETE, HEAD, PUT or MERGE.API documentationDocumentation over the possible requests can be viewed directly in the API on the following url: documentation is using the Swagger.io format – Swagger offers generated client code on different platforms.Further and more detailed documentation of the API can be found in the “Documentation” link.API testAs supplier, it is possible to use a testbroker in order to see if the planned implementation will work and how. Through medlem.ejendomstorvet.dk, one will be able to check if the data went through and ensure correct data before going live.Properties set to active are the only ones visible for users of the portal. Properties that have been uploaded using a test-broker are not visible for users at all.API Id, passwords and security keysSupplier Id, passwords and API-keys are handed out from Sima.dkOlder technologies (ASP Classic)In some cases, it is not possible to implement the libraries as provided by Hawk – an example of such a case is ASP Classic.For this case, we have developed a COM-object.Download this object incl. VBScript and Powershell examples here: the zip, install the object using the enclosed .bat-script using administrator privileges. Ensure that the installation is pointing to the filepath of the extracted files.After the installation of the object, you can test it by using the examples in the zip-file.OAUTH authetication api.ejendomstorvet.dk is an version of the API where the Hawk authentication is disabled, but acces is controlled by JWT bearer token.The Bearer token is delivered by . Following are required for at token request. - clientid, - clientsecret - audience. access rules is provided with the following headers- id- tokenkeyBrokernumber is used as normal in requests.Keys for access is provided by Ejendomstorvet.dk ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download