HMSREG API

HMSREG provides a RESTful interface to its database and framework functionality. Built while strictly following the REST architecture and its constraints, even the commonly ignored HATEOAS constraint.

Registrations

  • The Registrations API is a POST only API, so you cannot retrieve data from it
  • Authentication: Basic

REST API

  • The REST API can currently only provide resource data in JavaScript Object Notation (JSON), though XML is planned later down the line.
  • Authentication: Basic
  • Exposed resources can be discovered by browsing the API using your web browser.
  • HMSREG does not expose a resource for every HMSREG Module or Object, these are defined based on customer needs. This is to not expose more then necessary.

How to get access

Contact HMSREG Support on support@hmsreg.no to get access.

End Point

Base url: https://az-api.hmsreg365.no/

HTTP headers:

Content-Type:application/json
Accept:application/json

Note: only one record at a time is allowed for POST method.

URL /api/registreringer
Method POST
Success Response
  • Code: 200 OK
    Content:
            
                Reqistration is queued
            
                                                                    
Error Response
  • Code: 400 Bad Request
    Content:
    { "_error": "Missing required field Kortnr" }
  • Code: 401 Unauthorized
    Content:
    { "_error": "Login failed for user [user]." }
  • Code: 405 Method Not Allowed
    Content:
    { "_error": "Not found" }
Example
  • JSON Object description
                                        
                                                                        
        {
            "Kortnr": [Kortnr],
            "Retning": "Ankomst",
            "Tidspunkt": "2017-07-05T14:36:00",
            "Navn": "Ola Norman",
            "Orgnr": [Orgnr],
            "HmsRegnr": [HmsRegnr],
            "Kilde": "Test",
            "Korttype": "HMS",
            "Fødselsdato": "2017-07-05T00:00:00",
            "ExternalRef": [GUID]
        }
                                                                        
                                                                    

Object Description

Property names used in /registreringer.

Name Type Optional Size Description
Kortnr String No 8 Card number of HMS-kort
HmsRegnr Integer No - The unique identification number for a building site.
Retning String No 8 "Retning" describes the direction, in / out of the building site.
Valid values Description
Ankomst Direction in
Utgang Direction out
Tidspunkt String No - Use ISO 8601 format
2017-07-05T13:41:16+00:00
Navn String No 150 Name of person on HMS-kort (Firstname + LastName)
Orgnr String No 9 Organization number
Kilde String No 20 Provided to you by HMSREG after approval for api usage
Korttype String No 20 Type of card. "HMS" is used for HMS-kort
ExternalRef String Yes 36 GUID. 36 characters (Hyphenated) long. Provided for your reference.
ID Integer - - The identification of a specific registration

Examples

Postman collection. In Postman, click "Collection" and choose "Import". Paste this content in the box "Paste Raw Text".
                                
                                                    
{
	"info": {
		"_postman_id": "615b0b13-dad0-4855-a7ed-7a3eb6f8f38d",
		"name": "HMSREG API",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "https://az-api.hmsreg365.no/api/registreringer",
			"request": {
				"auth": {
					"type": "basic",
					"basic": [
						{
							"key": "password",
							"value": "",
							"type": "string"
						},
						{
							"key": "username",
							"value": "",
							"type": "string"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"name": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"Kortnr\": \"[CARDNO]\",\r\n    \"Retning\": \"Ankomst\",\r\n    \"Tidspunkt\": \"2017-07-05T14:36:00\",\r\n    \"Navn\": \"Ola Norman\",\r\n    \"Orgnr\": \"[ORGNO]\",\r\n    \"HmsRegnr\": [HMSREGNO],\r\n    \"Kilde\": \"Test\",\r\n    \"Korttype\": \"HMS\",\r\n    \"Fødselsdato\": \"2017-07-05T00:00:00\"\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://az-api.hmsreg365.no/api/registreringer",
					"protocol": "https",
					"host": [
						"az-api",
						"hmsreg365",
						"no"
					],
					"path": [
						"api",
						"registreringer"
					]
				}
			},
			"response": []
		}
	],
	"protocolProfileBehavior": {}
}
                                                    
                                                

Simple example for connecting to the api.

WebAPI.cs
                                    
using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace HmsRegApi
{
    class WebAPI
    {

        internal const string HmsRegApiUrl = "https://az-api.hmsreg365.no/";
        private static readonly Uri HmsRegApiUri = new Uri(HmsRegApiUrl, UriKind.Absolute);
        private static ICredentials _Credentials;
        private static HttpClientHandler _HttpClientHandler;
        private static HttpClient _HttpClient;

        public static void Initialize(ICredentials credentials)
        {
            _Credentials = credentials;

            _HttpClientHandler = new HttpClientHandler();
            _HttpClientHandler.Credentials = _Credentials;
            _HttpClientHandler.PreAuthenticate = true;

            _HttpClient = new HttpClient(_HttpClientHandler);
            _HttpClient.BaseAddress = HmsRegApiUri;

            var applicationJson = new MediaTypeWithQualityHeaderValue("application/json");
            _HttpClient.DefaultRequestHeaders.Accept.Add(applicationJson);
        }

        public static async Task GetAsync(string url)
        {
            var uri = new Uri(HmsRegApiUri, url);
            using (var response = await _HttpClient.GetAsync(url))
            {
                using (var responseStream = await response.Content.ReadAsStreamAsync())
                {
                    using (var textReader = new StreamReader(responseStream))
                    {
                        using (var jsonReader = new JsonTextReader(textReader))
                        {
                            return JsonSerializer.CreateDefault().Deserialize(jsonReader);
                        }
                    }
                }
            }
        }

        public static async Task PostAsync(string url, HttpContent formData)
        {
            using (var response = await _HttpClient.PostAsync(url, formData))
            {
                using (var responseStream = await response.Content.ReadAsStreamAsync())
                {
                    using (var textReader = new StreamReader(responseStream))
                    {
                        using (var jsonReader = new JsonTextReader(textReader))
                        {
                            return JsonSerializer.CreateDefault().Deserialize(jsonReader);
                        }
                    }
                }
            }
        }
    }
}

                                                        
                                                    
Program.cs
                                    
using System;
using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using System.Net;

namespace HmsRegApi
{
    class Program
    {
        static void Main(string[] args)

        {
            apiRegistreringer(null, null);
            Console.WriteLine("Wait for the api call or press any key to abort");
            Console.ReadKey();
        }

        private static async void apiRegistreringer(object sender, EventArgs e)
        {
            Console.WriteLine("HMS REG API");
            // NOTE: This is for test purpose only. Keep the credentials safe
            String user = "[user]";
            String password = "[password]";
            String encoded = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(user + ":" + password));
            var credentials = new NetworkCredential(user, password);
            WebAPI.Initialize(credentials);


            // POST TEST
            var values = new Dictionary()
                {
                    { "Kortnr", "[Kortnr]" },
                    { "Retning", "Ankomst" },
                    { "Tidspunkt", "2017-07-05T14:36:00" },
                    { "Navn", "Ola Normann" },
                    { "Orgnr", "[Orgnr]" },
                    { "HmsRegnr", "[HmsRegnr]" },
                    { "Kilde", "[Kilde]" },
                    { "Korttype", "HMS" },
                    { "ExternalRef", "245534f8-cefb-45a3-90e4-2d1a68c1a377" },
                };

            var content = new System.Net.Http.FormUrlEncodedContent(values);
            var result = await WebAPI.PostAsync("/api/registrering", content);
            JToken errorPostToken;
            if (result != null)
            {
                Console.WriteLine(result);
            }
            else if (result.TryGetValue("_error", out errorPostToken))
            {
                Console.WriteLine(errorPostToken);
            }
            else
            {
                Console.WriteLine("null");
            }

            // GET TEST
            var root = await WebAPI.GetAsync("/api/registreringer");
            var items = root.GetValue("_items") as JArray;
            JToken errorGetToken;
            if (items != null)
            {
                Console.WriteLine(items);
            }
            else if (root.TryGetValue("_error", out errorGetToken))
            {
                Console.WriteLine(errorGetToken);
            }
            else
            {
                Console.WriteLine("null");
            }

        }
    }
}

                                                        
                                                    

End Point

Base url: https://<your solution url>/api/rest

HTTP headers:

Content-Type:application/json
Accept:application/json

HMSREG er utviklet av programvareselskapet Omega.