Skip to content

User Subscriptions

A user can subscribe to categories, these categories are the ones to which the offers registered in the Semantic Engine belong, in order to be notified when a new offer related to the category to which the user is subscribed appears.

This section indicates the methods to perform the following actions:

Tip

It is possible to obtain which are the categories registered in the semantic engine using the following endpoint:

GET /semantic-engine/api/registration/categories-list

Create user subscription

To create a subscription it is only necessary to have the identifier of the user who wants to subscribe and the category to which he/she wants to subscribe.

POST /users/{user_id}/subscriptions

Subscribing a user to a category

In this case the user with ID UserID123 wants to subscribe to the category Health. 

curl -X 'POST' \
  'http://{NM}/api/v1/users/UserID123/subscriptions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "Health"
}'

Response: 

{
  "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
  "category": "Health",
  "active": true
}

Access to subscriptions

Once a subscription has been created, it is possible to access it by the following methods.

Get subscriptions by all users

This method returns all user subscriptions, whether the subscription is active or not.

GET /users/subscriptions

Get all users subscriptions

curl -X 'GET' \
  'http://{NM}/api/v1/users/subscriptions' \
  -H 'accept: application/json'
Response: 
[
  {
    "user_id": "user001",
    "subscriptions": [
      {
        "id": "6b820780-40ac-4cab-af4e-d53859e37e29",
        "category": "Manufacturing",
        "active": false
      }
    ]
  },
  {
    "user_id": "user002",
    "subscriptions": [
      {
        "id": "28bbc2d8-29a7-4f41-a0be-6ac9a4dd649d",
        "category": "Agriculture",
        "active": true
      }
    ]
  },
  {
    "user_id": "UserID123",
    "subscriptions": [
      {
        "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
        "category": "Health",
        "active": true
      }
    ]
  }
]

Get subscriptions by user ID

Get subscriptions for a specific user.

GET /users/{user_id}/subscriptions

Get the subscriptions by User ID

curl -X 'GET' \
  'http://{NM}/api/v1/users/UserID123/subscriptions' \
  -H 'accept: application/json'

Response: 

[
  {
    "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
    "category": "Health",
    "active": true
  }
]

Get subscription by user ID and subscription ID

Gets the subscription indicated by user ID and the subscription ID.

GET /users/{user_id}/subscriptions/{subscription_id}

Get the subscription by user ID and subscription ID

curl -X 'GET' \
  'http://{NM}/api/v1/users/UserID123/subscriptions/56c5f1ea-6fa3-40f7-ad4c-da2910d08f40' \
  -H 'accept: application/json'
Response: 
{
  "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
  "category": "Health",
  "active": true
}

Get user lists

We can obtain which users are subscribed to a category using the method indicated in the following subsection.

Tip

Only return those users who have their subscription active.

Get users subscribed to a category

GET /users/subscriptions/{category}

Get all users subscribed to a category

curl -X 'GET' \
  'http://{NM}/api/v1/users/subscriptions/Health' \
  -H 'accept: application/json'
Response: 
{
  "users": [
    "UserID123"
  ]
}

Modify subscriptions

It is possible to activate, deactivate a subscription and delete it from the system.

Activate subscription

PATCH /users/{user_id}/subscriptions/{subscription_id}/activate

Activate a subscription

curl -X 'PATCH' \
  'http://{NM}/api/v1/users/UserID123/subscriptions/56c5f1ea-6fa3-40f7-ad4c-da2910d08f40/activate' \
  -H 'accept: application/json'
Response: 
{
  "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
  "category": "Health",
  "active": true
}

Deactivate subscription

PATCH /users/{user_id}/subscriptions/{subscription_id}/deactivate

Deactivate a subscription

curl -X 'PATCH' \
  'http://{NM}/api/v1/users/UserID123/subscriptions/56c5f1ea-6fa3-40f7-ad4c-da2910d08f40/deactivate' \
  -H 'accept: application/json'
Response: 
{
  "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
  "category": "Health",
  "active": false
}

Remove subscription

DELETE /users/{user_id}/subscriptions/{subscription_id}

Deleting a subscription

curl -X 'DELETE' \
  'http://{NM}/api/v1/users/UserID123/subscriptions/56c5f1ea-6fa3-40f7-ad4c-da2910d08f40' \
  -H 'accept: application/json'
Response: 
{
  "id": "56c5f1ea-6fa3-40f7-ad4c-da2910d08f40",
  "category": "Health",
  "active": false
}

Supported use cases (features): Should list the use cases for this service, explaining each UC and how to use it. Which API calls should be called for the UC, detailed description of the API call parameters and response attributes and the order API calls are though to be performed regarding other services if is the case.

Tips, suggestions, restrictions or corner case treatment advices.

Guided examples: guided tutorial with a real reproducible example to understand the usage of each UC. Use example names and example parameters and link each step with explanations of what is supposed to happen, etc... At least one per component, desirable one per UC. A single guided example could cover several UC’s at once.

Last update: 2022-07-22
Created: 2022-04-06
Back to top