Commuty.ParkingAccess 2.5.5

Commuty API - Parking Access

This package acts as a client to communicate with the Commuty Parking Access API. It avoids you to deal with HTTP direclty and provides you proper data structures to work with the API.

Supported features are:

• Authenticate with Credentials
• Verify a user can access a parking site
• List all access rights for a day
• Report who entered/exited the parking
• Report a user that is known by the client but not by Commuty

Compatibility

This package is compatible with .NET Standard 1.1, which supports:

• .NET Core >= 1.0
• .NET Framework >= 4.5
• Mono >= 4.6
• Xamarin.iOS >= 10.0
• Xamarin.Mac >= 3.0
• Xamarin.Android >= 7.0
• Windows Phone >= 8.1
• Universal Windows Platform >= 10.0

Authentication

As an organisation, you must identify all your calls to the API using an Access Token. This token can be obtained by providing credentials (username/password) to a dedicated endpoint /token-requests.

Considering this token acquisition can take some time (up to 500ms), it should be kept in memory through multiple calls to the API (especially when using the functionnality "Verify a user can access a parking site", which requires a low latency). Each token is valid 24 hours.

Two types of clients

This package offers two types of clients, depending your constraints.

• A Fluent Client that authenticates automatically, refreshes its authentication (when expired) and exposes the API functionnalities without security matters. This is the "easy way".
• A Low Level Client that allows you to retrieve an access token and use it every time an API functionnality is called.

Which client fits best for you?

The type of client you need mostly depend whether you can keep your client instance in memory or not. If you can keep the client instance in memory through multiple calls to the API, then you should use the Fluent Client. However, if you want to use an access token manually (and keep it during multiple calls), you should use the Low Level Client.

Getting Started

First, add this package to your project as a dependency. Each class is exposed under the namespace Commuty.ParkingAccess.

FluentClient example in C# - List All Parking Access Rights

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToListAllAccessRights()
        {
            var client = ClientBuilder.Create()
                                      .WithCredentials("a-username", "a-password")
                                      .BuildFluentClient();

            // for example, you will list all access rights at midnight for today
            var allAccessRightsOfToday = await client.ListAllParkingAccessRights();

            // and at 8am, requesting new granted access rights for today
            var unreadOnly = true;
            var dryRun = false;
            var granted = true;
            var parkingSiteId = null;
            var includeAttributes = new List<AccessRightAttributeName>() { AccessRightAttributeName.Id, AccessRightAttributeName.Reason };
            var newAccessRightsOfToday = await client.ListAllParkingAccessRights(DateTime.Now, unreadOnly, dryRun, null, granted, parkingSiteId, includeAttributes);
        }
    }
}

FluentClient example in C# - Verify a user can access a parking site

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToVerifyAccessInRealTime()
        {
            var client = ClientBuilder.Create()
                                      .WithCredentials("a-username", "a-password")
                                      .BuildFluentClient();

            // each time a user scan its id at the parking entrance, for example
            var isAllowedToEnter = await client.VerifyAccess("a-parking-site-id", UserId.FromEmail("someone@your-company.com"));
            if (isAllowedToEnter)
            {
                OpenTheBarrier();
            }
            else
            {
                DoNotOpenTheBarrier();
            }
        }
    }
}

FluentClient example in C# - Report who entered/exited the parking

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportAccessLogs()
        {
            var client = ClientBuilder.Create()
                                      .WithCredentials("a-username", "a-password")
                                      .BuildFluentClient();

            // create a list of one or multiple accesses
            var accesses = new List<AccessLog>
            {
                AccessLog.CreateInAccessLog(UserId.FromEmail("someone@your-company.com"), new DateTime(2019, 10, 01, 08, 0, DateTimeKind.Utc)),
                AccessLog.CreateOutAccessLog(UserId.FromEmail("someone@your-company.com"), new DateTime(2019, 10, 01, 17, 0, DateTimeKind.Utc))
            };

            // send the accesses at regular interval (or send each access instantaneously)
            var savedAccessId = await client.ReportAccessLogs("a-parking-site-id", accesses);
            // you can save the 'savedAccessId' for future reference or simply discard it

        }
    }
}

FluentClient example in C# - Report a user that is known by the client but not by Commuty

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportAMissingUserId()
        {
            var client = ClientBuilder.Create()
                                      .WithCredentials("a-username", "a-password")
                                      .BuildFluentClient();

            // send every user that you know should be known to Commuty but isn't
            await client.ReportMissingUserId(UserId.FromBadgeNumber("444719"));
        }
    }
}

FluentClient example in C# - Report the number of available spots on a parking site

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportTheNumberOfAvailableSpots()
        {
            var client = ClientBuilder.Create()
                                      .WithCredentials("a-username", "a-password")
                                      .BuildFluentClient();

            var spotsThatAreAvailable = 55; // this is mandatory
            var totalSpotsOnTheSite = 101; // this can be null (int?)
            await client.ReportAvailableSpotCount("a-parking-site-id", spotsThatAreAvailable, totalSpotsOnTheSite);
        }
    }
}

LowLevelClient example in C# - List All Parking Access Rights

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToListAllAccessRights()
        {
            var client = ClientBuilder.Create()
                                      .BuildLowLevelClient();

            var accessToken = await client.Authenticate("a-username", "a-password");

            // for example, you will list all access rights at midnight for today
            var allAccessRightsOfToday = await client.ListAllParkingAccessRights(accessToken);

            // and at 8am, requesting new granted access rights for today
            try
            {
                var unreadOnly = true;
                var dryRun = false;
                var includeAttributes = new List<AccessRightAttributeName>() { AccessRightAttributeName.Id, AccessRightAttributeName.Reason };
                var granted = true;
                var parkingSiteId = null;
                var newAccessRightsOfToday = await client.ListAllParkingAccessRights(DateTime.Now, unreadOnly, dryRun, null, granted, parkingSiteId, includeAttributes, accessToken);
            }
            catch (WrongTokenException e)
            {
                // the token could expire in the meantime
                if (e.IsExpired()) {
                    accessToken = await client.Authenticate("a-username", "a-password");
                    var newAccessRightsOfToday = await client.ListAllParkingAccessRights(DateTime.Now, unreadOnly, dryRun, null, granted, parkingSiteId, includeAttributes, accessToken);
                }
                else
                {
                    throw e;
                }
            }
        }
    }
    
}

LowLevelClient example in C# - Verify a user can access a parking site

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToVerifyAccessInRealTime()
        {
            var client = ClientBuilder.Create()
                                      .BuildLowLevelClient();

            var accessToken = await client.Authenticate("a-username", "a-password");

            // each time a user scan its id at the parking entrance, for example
            try
            {
                var isAllowedToEnter = await client.VerifyAccess("a-parking-site-id", UserId.FromEmail("someone@your-company.com"), accessToken);
                if (isAllowedToEnter)
                {
                    OpenTheBarrier();
                }
                else
                {
                    DoNotOpenTheBarrier();
                } 
            }
            catch (WrongTokenException e)
            {
                // the token could expire in the meantime
                if (e.IsExpired())
                {
                    // refresh token
                }
                else
                {
                    throw e;
                }
            }
        }
    }
    
}

LowLevelClient example in C# - Report who entered/exited the parking

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportAccessLogs()
        {
            var client = ClientBuilder.Create()
                                      .BuildLowLevelClient();

            var accessToken = await client.Authenticate("a-username", "a-password");

            // create a list of one or multiple accesses
            var accesses = new List<AccessLog>
            {
                AccessLog.CreateInAccessLog(UserId.FromEmail("someone@your-company.com"), new DateTime(2019, 10, 01, 08, 0, DateTimeKind.Utc)),
                AccessLog.CreateOutAccessLog(UserId.FromEmail("someone@your-company.com"), new DateTime(2019, 10, 01, 17, 0, DateTimeKind.Utc))
            };

            try
            {
                // send the accesses at regular interval (or send each access instantaneously)
                var savedAccessId = await client.ReportAccessLogs("a-parking-site-id", accesses, accessToken);
                // you can save the 'savedAccessId' for future reference or simply discard it
            }
            catch (WrongTokenException e)
            {
                // the token could expire in the meantime
                if (e.IsExpired())
                {
                    // refresh token
                }
                else
                {
                    throw e;
                }
            }
        }
    }
}

LowLevelClient example in C# - Report a user that is known by the client but not by Commuty

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportAMissingUserId()
        {
            var client = ClientBuilder.Create()
                                      .BuildLowLevelClient();

            var accessToken = await client.Authenticate("a-username", "a-password");

            try
            {
                // send every user that you know should be known to Commuty but isn't
                await client.ReportMissingUserId(UserId.FromBadgeNumber("444719"), accessToken);
            }
            catch (WrongTokenException e)
            {
                // the token could expire in the meantime
                if (e.IsExpired())
                {
                    // refresh token
                }
                else
                {
                    throw e;
                }
            }
        }
    }
}

LowLevelClient example in C# - Report the number of available spots on a parking site

using System;
using System.Threading.Tasks;
using Commuty.ParkingAccess;

namespace Example
{
    class Test
    {
        async Task HowToReportTheNumberOfAvailableSpots()
        {
            var client = ClientBuilder.Create()
                                      .BuildLowLevelClient();

            var accessToken = await client.Authenticate("a-username", "a-password");

            try
            {
                var spotsThatAreAvailable = 55; // this is mandatory
                var totalSpotsOnTheSite = 101; // this can be null (int?)
                await client.ReportAvailableSpotCount("a-parking-site-id", spotsThatAreAvailable, totalSpotsOnTheSite, accessToken);
            }
            catch (WrongTokenException e)
            {
                // the token could expire in the meantime
                if (e.IsExpired())
                {
                    // refresh token
                }
                else
                {
                    throw e;
                }
            }
        }
    }
}

Using a proxy to access the API

Both LowLevelClient and FluentClient supports communication through a proxy. This proxy configuration must be an implementation of the interface System.Net.IWebProxy, such as System.Net.WebProxy.

var client = ClientBuilder.Create()
                          .WithProxy(new WebProxy("http://acme.com:1234", true))
                          .BuildLowLevelClient();