...
This document also includes how to connect to the APIs and how to read from NIFs Enterprise Service Bus (ESB) hosted on Microsoft Azure cloud.
Preparations
For any 3. party to connect to and consume NIF APIs, the request must go through the following stages:
Identification
Authentication
Authorization
Identification
A 3.party must be registered with NIF to be correctly identified. When registered, the main contact person at the 3.party receives an invitation email to the NIF API developer portal.
...
By clicking the link in the email, the 3.party can setup their user and login credentials on the NIF API developer portal. These credentials must not be shared with any non-registered entity.
...
DST (test environment): https://api-portal-dst.nif.no/
PROD (production environment): https://api-portal.nif.no/
Authentication
When logging into the NIF API developer portal, one may view a list of available NIF API products.
...
The 3.party can find its API Primary key in the portal. This key will be used for authentication when requesting APIs.
...
Authorization
The 3.party needs an access token to be authorized, in order to request and manage club data. Club data is highly sensitive and secured. Only 3.parties authorized by the clubs through legal contracts can access respective club data.
...
This access token must be fetched by the 3.party by invoking the GET Token API (Gets the bearer token to access APIs for specific club) in the NIF API developer portal. To get the access token of a club, the 3.party needs to provide clubID and API-version and developerUserId.
clubId: is given to you by NIF
version: 1
developerUserId: firstname-lastname-domain-xx
Ocp-Apim-Subscription-Key: auto completed
...
If the developer email id is donald.duck@idrettsforbundet.no then the developerUserID for this developer will be donald-duck-idrettsforbundet-no.
The GET Token API is restricted to the portal and cannot be accessed and/or invoked from outside (e.g. directly through code or web API tools).
The GET Token API is restricted to the portal and cannot be accessed and/or invoked from outside (e.g. directly through code or web API tools).
NOTE: Along with the API key the access token is highly confidential and must not be shared with unauthorized entities in any way. Both the API key and access token are mandatory parameters in request header of all APIs
Enterprise Service Bus Queue (ESBQ)
In addition to the NIF API developer portal, the 3.party will also receive a connection string to NIF’s ESB Queue in a separate email. Please read further for more details on using the ESB Queues to listen and consume messages.
Communication
There will be two modes of communication between NIF and the 3.parties
NIF API (REST API)
Microsoft Azure Service Bus Queue
NIF API (REST API)
The REST API uses HTTP requests to GET, PUT, POST and DELETE data.
Using this communication, the 3.party can fetch initial lookup data and provide data changes to NIF through HTTPS communication.
Required parameters to be set as header in NIF API requests are:
Ocp-Apim-Subscription-Key
This key defines access rights granted to the 3.party. This key is a mandatory parameter in API request header to invoke NIF APIs to identify and authenticate the 3.party.
Authorization
To authorize an API request, the 3.party must provide the authorization token in API request header. This authorization token is unique to a club for a 3.party. These keys will define data access granted to the 3.party for accessing and managing data on behalf of the club.
Service Bus Queue
The 3.party will receive data updates from NIF via a dedicated Azure Service Bus Queue.
NIF will publish relevant changes to the 3.party´s scope to the Azure Service Bus Queue. A message with changed object and delta changes is provided. The 3. party subscribes to the Azure Service Bus Queue to consume posted messages.
Note: Each 3.party will have a dedicated instance of Service Bus Queue. All messages concerning clubs who has an engagement with the given 3.party will be published on the party´s dedicated queue. The messages will be in FIFO (In technical terms it is a Session Enabled Queue).
Once a message is read from the Service Bus Queue, it will be removed from the queue. NIF does not keep a history of messages sent to the 3.party´s queue. The 3.party must maintain the message history if they need to refer to it later, after reading it from the queue.
Messages in the Queue will follow the below mentioned schema:
Message Properties
...
Property
...
Type
...
Value
...
ObjectId
...
int
...
Id of the entity
...
EntityName
...
string
...
Name of the entity.
...
ChangeType
...
Change type enumeration
...
1 - Added
2 - Modified
3 - Deleted
9 - Informational
...
Messages with change types ‘Added’ or ‘Modified’ have delta object schema and data.
Informational messages will always have a full object schema and data.
Message Body
The message body contains the JSON message defined in Queue Message Structure.
Service Bus Queue Guidelines
Service Bus Queue session is enabled, so the listener must be configured with the option for session.
Due to the nature of sessions, all messages will be received in FIFO manner.
The listener can be configured in different modes.
o ReceiveAndDelete: In this mode the message is removed from queue once received.
o Peek: In this mode the messages is not removed from the queue until the receiver mark that Message as “Complete”.
Once the message is removed from the queue it cannot be recovered or replayed.
The informational messages (ChangeType = 9) will be received before the main change.
Enumerations
Membership Status
...
Name
...
Value
...
Comment
...
Active
...
2
...
Membership is active
...
Cancelled
...
4
...
If membership is cancelled by user or enddate has reached
Queue Message Structure
Entities posted to Queue
...
No
...
Entities
...
Publish Message to Queue
...
1
...
TpMembership
...
When a person is created and then membership is assigned via POST Membership API
When a club chooses to switch 3.party, NIF allows an overlapping period between going live on new solution and shutting down integration on old solution. This grace period is 30 days. During this period if any membership is registered on either of the solutions, then the other 3.party will receive this message in their queue.
...
2
...
TpActiveMembership
...
Similar to the aforementioned scenario, if active membership is registered in either of the 3.parties solutions during the overlapping period, the other solution will receive this message in their queue.
...
3
...
TpPerson
...
When a person is created through POST Membership API
Additionally, similar to the aforementioned scenario, if person is registered in either of the Integration Partner solutions during the overlapping period, the other solution will receive this message in their queue.
...
4
...
TpPersonContactInformation
...
When person contact information is updated.
...
5
...
ToOrg
...
When an organization is created or updated.
...
6
...
ToOrgTerminationReason
...
When an organization is terminated
...
7
...
ToOrgType
...
When there are any changes in org type master/lookup table.
...
8
...
ToSport
...
When any sport is created or updated.
...
9
...
TpMembershipPeriod
...
When club membership Period is updated
...
10
...
Tp_PaymentType
...
When payment is type is added or updated
...
11
...
Tp_PaymentStatus
...
When payment status is updated
Message Body Schema
...
No.
...
Entities JSON Schema
...
1
...
...
2
...
...
3
...
...
4
...
...
5
...
...
6
...
...
7
...
...
8
...
...
9
...
...
10
...
...
11
...
Entities Relationships
...
...
Change History
No | Changes | Date |
1 | Remove membership payment and active membership payment entity messages from section Entities Posted to Queue Remove payment entity JSON schema for membership payment and active membership payment in section Entities JSON schema | 6. February 2020 |
2 | In POST Membership, SSN would not be mandatory. In POST Membership, NationalityID would be used to decide is membership request for Norwegian or Foreign member. List of Membership Status IDs updated with descriptions. ToOrgtype JSON added | 11. March 2020 |
3 | Added description of how to generate developerUserID Updated simplified flow for the membership Updated person merge with all messages related to person merge | 22. May 2020 |
4 | Updated person merge message sequence as per new implementation | 23. June 2020 |
5 | Specify MembershipRequest-guidelines for 3.party Remove SSN in MembershipRequest | 14. October 2020 |
6 | Added sections for Corporate Sports APIs | 11. December 2020 |
7 | Added support for Allidrett | 5. March 2021 |
8 | Extended response in PaymentDetails | 1. April 2022 |
Preparations
For any 3. party to connect to and consume NIF APIs, the request must go through the following stages:
Identification
Authentication
Authorization
Identification
A 3.party must be registered with NIF to be correctly identified. When registered, the main contact person at the 3.party receives an invitation email to the NIF API developer portal.
...
By clicking the link in the email, the 3.party can setup their user and login credentials on the NIF API developer portal. These credentials must not be shared with any non-registered entity.
...
DST (test environment): https://api-portal-dst.nif.no/
PROD (production environment): https://api-portal.nif.no/
Authentication
When logging into the NIF API developer portal, one may view a list of available NIF API products.
...
The 3.party can find its API Primary key in the portal. This key will be used for authentication when requesting APIs.
...
Authorization
The 3.party needs an access token to be authorized, in order to request and manage club data. Club data is highly sensitive and secured. Only 3.parties authorized by the clubs through legal contracts can access respective club data.
...
This access token must be fetched by the 3.party by invoking the GET Token API (Gets the bearer token to access APIs for specific club) in the NIF API developer portal. To get the access token of a club, the 3.party needs to provide clubID and API-version and developerUserId.
clubId: is given to you by NIF
version: 1
developerUserId: firstname-lastname-domain-xx
Ocp-Apim-Subscription-Key: auto completed
...
If the developer email id is donald.duck@idrettsforbundet.no then the developerUserID for this developer will be donald-duck-idrettsforbundet-no.
The GET Token API is restricted to the portal and cannot be accessed and/or invoked from outside (e.g. directly through code or web API tools).
The GET Token API is restricted to the portal and cannot be accessed and/or invoked from outside (e.g. directly through code or web API tools).
NOTE: Along with the API key the access token is highly confidential and must not be shared with unauthorized entities in any way. Both the API key and access token are mandatory parameters in request header of all APIs
Enterprise Service Bus Queue (ESBQ)
In addition to the NIF API developer portal, the 3.party will also receive a connection string to NIF’s ESB Queue in a separate email. Please read further for more details on using the ESB Queues to listen and consume messages.
Communication
There will be two modes of communication between NIF and the 3.parties
NIF API (REST API)
Microsoft Azure Service Bus Queue
NIF API (REST API)
The REST API uses HTTP requests to GET, PUT, POST and DELETE data.
Using this communication, the 3.party can fetch initial lookup data and provide data changes to NIF through HTTPS communication.
Required parameters to be set as header in NIF API requests are:
Ocp-Apim-Subscription-Key
This key defines access rights granted to the 3.party. This key is a mandatory parameter in API request header to invoke NIF APIs to identify and authenticate the 3.party.
Authorization
To authorize an API request, the 3.party must provide the authorization token in API request header. This authorization token is unique to a club for a 3.party. These keys will define data access granted to the 3.party for accessing and managing data on behalf of the club.
Service Bus Queue
The 3.party will receive data updates from NIF via a dedicated Azure Service Bus Queue.
NIF will publish relevant changes to the 3.party´s scope to the Azure Service Bus Queue. A message with changed object and delta changes is provided. The 3. party subscribes to the Azure Service Bus Queue to consume posted messages.
Note: Each 3.party will have a dedicated instance of Service Bus Queue. All messages concerning clubs who has an engagement with the given 3.party will be published on the party´s dedicated queue. The messages will be in FIFO (In technical terms it is a Session Enabled Queue).
Once a message is read from the Service Bus Queue, it will be removed from the queue. NIF does not keep a history of messages sent to the 3.party´s queue. The 3.party must maintain the message history if they need to refer to it later, after reading it from the queue.
Messages in the Queue will follow the below mentioned schema:
Message Properties
Property | Type | Value |
ObjectId | int | Id of the entity |
EntityName | string | Name of the entity. |
ChangeType | Change type enumeration | 1 - Added 2 - Modified 3 - Deleted 9 - Informational |
Note:
Messages with change types ‘Added’ or ‘Modified’ have delta object schema and data.
Informational messages will always have a full object schema and data.
Message Body
The message body contains the JSON message defined in Queue Message Structure.
Service Bus Queue Guidelines
Service Bus Queue session is enabled, so the listener must be configured with the option for session.
Due to the nature of sessions, all messages will be received in FIFO manner.
The listener can be configured in different modes.
o ReceiveAndDelete: In this mode the message is removed from queue once received.
o Peek: In this mode the messages is not removed from the queue until the receiver mark that Message as “Complete”.
Once the message is removed from the queue it cannot be recovered or replayed.
The informational messages (ChangeType = 9) will be received before the main change.
Enumerations
Membership Status
Name | Value | Comment |
Active | 2 | Membership is active |
Cancelled | 4 | If membership is cancelled by user or enddate has reached |
Queue Message Structure
Entities posted to Queue
No | Entities | Publish Message to Queue
|
1 | TpMembership | When a person is created and then membership is assigned via POST Membership API When a club chooses to switch 3.party, NIF allows an overlapping period between going live on new solution and shutting down integration on old solution. This grace period is 30 days. During this period if any membership is registered on either of the solutions, then the other 3.party will receive this message in their queue. |
2 | TpActiveMembership | Similar to the aforementioned scenario, if active membership is registered in either of the 3.parties solutions during the overlapping period, the other solution will receive this message in their queue. |
3 | TpPerson | When a person is created through POST Membership API Additionally, similar to the aforementioned scenario, if person is registered in either of the Integration Partner solutions during the overlapping period, the other solution will receive this message in their queue. |
4 | TpPersonContactInformation | When person contact information is updated. |
5 | ToOrg | When an organization is created or updated. |
6 | ToOrgTerminationReason | When an organization is terminated |
7 | ToOrgType | When there are any changes in org type master/lookup table. |
8 | ToSport | When any sport is created or updated. |
9 | TpMembershipPeriod | When club membership Period is updated |
10 | Tp_PaymentType | When payment is type is added or updated |
11 | Tp_PaymentStatus | When payment status is updated |
Message Body Schema
No. | Entities JSON Schema
|
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 |
Entities Relationships
...
The API endpoints allow 3.parties to perform operations on a club’s behalf. The only prerequisites to use an API endpoint is a valid subscription key and an authorization key. The APIs utilize JSON data format for responses (and in some cases, for requests).
...
Endpoints
Annet
Table of Content
...
7.8.2 Corporate Sports API 628 Person merge 64
...
9.5 TpPersonContactInformation 89
9.7 ToOrgTerminationReason 101
9.9 TpActiveMembershipStatus 105
1 Change History
...
No
...
Changes
...
Date
...
1
...
· Remove membership payment and active membership payment entity messages from section Entities Posted to Queue
· Remove payment entity JSON schema for membership payment and active membership payment in section Entities JSON schema
...
06-Feb-2020
...
2
...
· In POST Membership, SSN would not be mandatory.
· In POST Membership, NationalityID would be used to decide is membership request for Norwegian or Foreign member.
· List of Membership Status IDs updated with descriptions.
· ToOrgtype JSON added
...
11-Mar-2020
...
3
...
· Added description of how to generate developerUserID
· Updated simplified flow for the membership
· Updated person merge with all messages related to person merge
...
22-May-2020
...
4
...
· Updated person merge message sequence as per new implementation
...
23-Jun-2020
...
5
...
· Specify MembershipRequest-guidelines for 3.party
· Remove SSN in MembershipRequest
...
14-Oct-2020
...
6
...
· Added sections for Corporate Sports APIs
...
11-Dec-2020
...
7
...
· Added support for Allidrett
...
9.7 ToOrgTerminationReason 101
9.9 TpActiveMembershipStatus 105