API Getting Started



PurposeThis documents describes in whole how the Partner 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 _Toc1458848 \h 1Security PAGEREF _Toc1458849 \h 2Storage of secret key PAGEREF _Toc1458850 \h 2Time syncing PAGEREF _Toc1458851 \h 2Cross site scripting PAGEREF _Toc1458852 \h 2Calculating the mac PAGEREF _Toc1458853 \h 2Example PAGEREF _Toc1458854 \h 3Errorhandling PAGEREF _Toc1458855 \h 3HTTP status 400 – Bad request PAGEREF _Toc1458856 \h 3HTTP status 500 – Internal server error PAGEREF _Toc1458857 \h 3Compression PAGEREF _Toc1458858 \h 4Caching PAGEREF _Toc1458859 \h 4HTTP Method override PAGEREF _Toc1458860 \h 4API documentation PAGEREF _Toc1458861 \h 4API test PAGEREF _Toc1458862 \h 4API Id, passwords and security keys PAGEREF _Toc1458863 \h 5Older technologies (ASP Classic) PAGEREF _Toc1458864 \h 5SecurityThe 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 /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 partners’ 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: The 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 caching 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 Id, passwords and security keysPartner Id, passwords and API-keys are handed out from Sima.dk ................
................

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

Google Online Preview   Download