| Info |
|---|
| Table of Contents |
|---|
Introduction
This document covers the API definitions developed by Norges idrettsforbund og olympiske og paralympiske komité (NIF). NIF API products consists of a set of RESTful services.
...
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.
...
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.
...
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.
...
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.
...
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).
...
HTTP/1.1 400 Bad Request Content-Type: application/json |
General Response Codes
HTTP Success Codes
Code | Text | Description |
200 | The request has succeeded | The meaning of success depends on the HTTP method: GET: The resource has been fetched and is transmitted in the message body. PUT or POST: The resource describing the result of the action is transmitted in the message body. |
HTTP Error Codes
Code | Text | Description |
400 | Bad Request | This response means the server did not understand the request due to invalid syntax. |
401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. |
404 | Not Found | The server cannot find the requested resource. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. |
500 | Internal Server Error | The server has encountered a situation it does not know how to handle. |
502 | Bad Gateway | This error response means the server, while working as a gateway to get the response needed to handle the request, received an invalid response. |
Commonly used Data types
Type | Description | Format |
Integer | Whole positive or negative numbers |
|
Date | Date | yyyy-mm-dd |
DateTime | Date and time information | yyyy-mm-dd hh:mm:ss |
Decimal | Floating point values | 000.00 |
String | Free text |
|
Boolean | True/false values | true / false |
Using APIs
...
GET Token
Overview
Method | API Endpoint | Description |
GET | api/v{version}/auth/token/{clubId} | Allows 3.partiesr to get authorization token to be used for subsequent API requests. This API must be called from the Developer portal of Azure API Management. The representative must login with username and password. |
...
[ “token” : “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkhpdGVzaFBhcnQyIiwiQ2x1YklkIjoiMTk0MzAiLCJDbHViRGV0YWlsIjoiMTk0MzB-NzF-LTQzIiwibmJmIjoxNTY2OTc0OTA0LCJleHAiOjE1NjY5Nzg1MDQsImlhdCI6MTU2Njk3NDkwNCwiaXNzIjoic2VsZiIsImF1ZCI6ImZ1bi10cGkifQ._YXZwmdSMhmxldBew48Ii1BbZAXgGwXAfUPuEbV40c8” ] |
GET Sports
Overview
Method | API Endpoint | Description |
GET | /api/v{version}/sports | Allows Integration Partners to download all NIF sports. |
...
[ |
GET Countries
Overview
...
Response Format | JSON |
Requires Authentication | Yes |
GET Organization Structure
External Membership API (vanlige idrettslag)
Overview
Method | API Endpoint | Description |
GET | /api/v{version}/organization/structure | Gets the organization structure (branches) of club along with its details. Allidrett: |
...
Response Format | JSON |
Requires Authentication | Yes |
Company Sports API (Bedriftsidrettslag)
Overview
Method | API Endpoint | Description |
GET | /api/v{version}/organization/structure | Gets the organization structure (branches) of Corporate Sports Club’s along with its details. |
...
{ "clubId": 16235, |
POST Membership
External Membership API
Overview
Method | API Endpoint | Description |
POST | /api/v{version}/membership | Allows adding a membership for Norwegian or foreign persons using POST Membership. Membership represents the connection of a person with a club and/or its branch for a specific sport. If a person´s nationality is Norwegian, membership request would be considered as Norwegian person request, otherwise request would be considered as a foreign person request. The API adds branch level membership data. It will also add club level membership. If clubId is passed in the request the API adds club level membership. If a branchId is passed, the request adds branch level membership. Allidrett: If the Person already exists in the third party membership solution, the PersonId should be sent in the AddMembership-request. When the membership request contains PersonId then all the information is fetched from NIF by using PersonId. If PersonId is not passed in the request, the person is searched for, based on first name, last name, date of birth, gender, postal code and nationality. If no result in this search, a new person will attempt to be created. If the data is imprecise or wrong, and the person most likely already exists, a failure in user verification will arise when end user tries to validate with SSN. If the PersonId is sent and the response is “invalid person id”, the third party is not synchronized correctly. Work around is to send exact person information, according to entry in The National Population Register (Folkeregisteret). Club level membership requests are subject to a two-phase verification active for 24 hours. The verification link is sent to the user via email and SMS. This must be passed for request to be fulfilled. After user verification an OTP code is sent by SMS and must be entered to the two-phase temporary site. Once completed request is passed on. If a person is already validated in NIFs database, no OTP is required, and the person will not be able to change any personal information in the verification form. All personal information is kept updated by the person itself in Min idrett, by logging in with Idrettens ID. As soon as two-phase verification is completed successfully, person club and branch level membership are added. This API will respond with traceId along with other needed parameters. This traceId will be used to trace the request response with messages received in enterprise service bus queue. After two-phase verification, person and membership records in queue has traceId. In case the person is already validated there is no traceId in the message in the queue or the response. If Membership at Club or Branch level system will respond with existing MembershipId/ActiveMembershipId. Entities to get affected by this API: Tp_Person |
...
| Code | Text | Description |
1 | 200 | Success |
|
2 | 1001 | Either PersonId or a combination of (FirstName, LastName, BirthDate, PostCode, NationalityId) must be supplied. |
|
3 | 1002 | Invalid Person Id |
|
4 | 1006 | Invalid Branch Id |
|
5 | 1007 | Start date cannot be past/future year date. |
|
6 | 1010 | Either Email or MobilePhone and CountryCode must be supplied. |
|
7 | 1013 | Branch level membership information missing. |
|
8 | 1018 | Invalid club Id. |
|
9 | 1034 | Person not found. |
|
10 | 1036 | Start date is required. |
|
11 | 1038 | Branch start date must be grater then membership start date. |
|
12 | 1039 | Invalid request parameters. |
|
13 | 1042 | Group level membership for Club is not allowed. |
|
14 | 3001 | Membership not found for specific period from date. |
|
Membership Request Example
| Code Block | ||
|---|---|---|
| ||
{
"startDate": "2019-08-27",
"isClubLevel": true,
"person": {
"personId": 8756934, -- NB: If personId is provided, all person properties ignored.
"firstName": "Ola",
"lastName": "Dunk",
"birthDate": "1980-07-05",
"postCode": "0010",
"email": "helge.carter@nic.com",
"mobilePhone": "85569745",
"genderId": 2,
"countryId": 1500152,
"nationalityId": 1500152,
"addressLine1": "Blålyngveien 89",
"addressLine2": "",
"city": "Oslo",
"privatePhone": "78553987",
"workPhone": "78553977",
"isSecretAddress": true,
"isSecretWorkPhone": true,
"isSecretMobilePhone": false,
"isSecretEmail": true,
"countryCode": "+47",
"isSecretPrivatePhone": true
},
"sports": [
{
"branchId": 827527,
"sportId": 220,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
},
{
"branchId": 819760,
"sportId": 207,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
]
} |
Membership Response Example
| Code Block |
|---|
{
"personId": 8756934,
"membershipId": 0,
"clubId": 19428,
"clubName": "Gjermundsen Auto B.I.L.",
"startDate": "2019-08-27",
"traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201",
"sports”: [
{
"branchId": 819760,
"sportId": 207,
"branchName": "Berg IL",
"activeMembershipId": 0
},
{
"branchId": 827527,
"sportId": 220,
"branchName": "Berg IL",
"activeMembershipId": 0
}
],
"responseMessage": "Membership request is accepted at Club Level.
It is pending for two phase verification."
} |
| Note |
|---|
NOTE: If response contains personId and no membershipId, NEVER use this personId until the two phase verification is done by the end user, and the information is provided on the 3. party´s subscription queue. |
Allidrett request example
| Code Block |
|---|
{
"startDate": "2019-08-27",
"isClubLevel": true,
"person": {
"personId": "",
"firstName": "Dolly",
"lastName": "Duck",
"birthDate": "1980-07-05",
"postCode": "0010",
"email": "dd@mailinator.com",
"mobilePhone": "85569745",
"genderId": 2,
"countryId": 1500152,
"nationalityId": 1500152,
"addressLine1": "Blålyngveien 8",
"addressLine2": "",
"city": "Oslo",
"privatePhone": "78553987",
"workPhone": "78553977",
"isSecretAddress": true,
"isSecretWorkPhone": true,
"isSecretMobilePhone": false,
"isSecretEmail": true,
"countryCode": "+47",
"isSecretPrivatePhone": true
},
"sports": [
{
"branchId": 827527,
"sportId": 220,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
],
"groups": [
{
"sportId": 0,
"groupId": 544901,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
]
} |
Allidrett response example
| Code Block |
|---|
{
"personId": 8756934,
"membershipId": 0,
"clubId": 19428,
"clubName": "Gjermundsen Auto B.I.L.",
"startDate": "2019-08-27",
"traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201",
"sports": [],
"groups": [],
"person": null,
"responseMessage": "Membership request is accepted at Club Level.
It is pending for two phase verification."
} |
Endpoints
Annet
Table of Content
...
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 | 05-Mar-2021 |
...