GraphQL is an Open-Source data query and manipulation language for APIs. Like a REST API, it is based on HTTP, but it comes with a few features that eliminate the following challenges:

• Overfetching: Downloading superfluous data
• Underfetching and the n+1 problem
• Fixed data structure defined by the server
• No strong typing
• Polling for updates

Visit graphql.org to learn more about the basics of GraphQL.

In this example we want to get a list of SIM cards from our inventory. We need the following items:

• ICCID
• IMEI
• Monthly Data Volume

We want the result sorted by Monthly Data Volume in descending order. The result should be limited to 3 items.

curl command line example:

curl -g \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY_HERE" \
-d '{
  "variables": {
    "order": { "monthly_data_volume": "desc" },
    "limit": 3
  },
  "query": "query ListSims($filter: SimFilterInput, $order: SimListOrder, $limit: Int!, $nextToken: String) { listSims(filter: $filter, order: $order, limit: $limit, nextToken: $nextToken) { items { iccid imei monthly_data_volume } }}"
}' \
https://graphql.api.whereversim.de/graphql

JSON based response:

{
  "data": {
    "listSims": {
      "items": [
        {
          "iccid": "9876543210123456789",
          "imei": "869876543210123",
          "monthly_data_volume": 6012954214
        },
        {
          "iccid": "9876543211234567890",
          "imei": "869876543211234",
          "monthly_data_volume": 501219328
        },
        {
          "iccid": "9876543212345678901",
          "imei": "869876543212341",
          "monthly_data_volume": 31457280
        }
      ]
    }
  }
}

The following table shows a list of the possible SIM status:

Numeric representation	Name	Description
1	No Status	Status of SIM is unknown
2	Activated	SIM is activated
3	Issued	SIM is issued (delivery condition)
4	Deleted	SIM is deleted
5	Deactivated	SIM is deactivated
6	Test Ready	SIM is test ready and switches to Activated once the test data, SMS or voice volume is exceeded
7	Retired	SIM is retired. Cannot be activated again
8	Activation ready	SIM is ready for activation
9	Inventory	SIM is in inventory
10	Replaced	SIM is replaced
11	Activation Pendant	SIM activation is pendant
12	Suspended	SIM is suspended
13	Waiting for Activation	SIM is in transition to Activated status
14	Waiting for Deactivation	SIM is in transition to Deactivated status
15	Test Usage Exhausted	SIM is deactivated because of exhausted test usage
16	Data Usage Exhausted	SIM is deactivated because of exhausted data usage
17	Waiting for Activation Ready	SIM is in transition to Activation Ready status
18	SMS Limit exceeded	SIM is deactivated because of exceeded SMS limit
19	Voice Limit exceeded	SIM is deactivated because of exceeded voice limit
20	IMEI unauthorized	SIM is deactivated because the IMEI of the current device does not match the one configured in the IMEI lock

The following table shows a list of the provider / product ids:

ID	provider / product
1	connect+
2	tech+ pro
3	tech+
4	data+
5	link+

The following table shows a list of the possible SIM event types:

event type	description
consumption	Consumption of data, sms or voice for the current day and month
lifecycle	Changes of the SIM status
presence	Data connection established or disconnected
cancelLocation	Cancel location send
imeiLockSwitch	IMEI lock enabled/disabled/auto-detect switch
imeiUnauthorized	SIM card has been used with an unauthorized IMEI
usageNotification	Usage notification send

The nextToken principle is used when a query can return many results. One example of this is the listSims query. This query requires a limit to be set for the maximum number of results per query. If there are more results than the limit, a nextToken is returned if queried. This nextToken can be used for another call of listSims to get the more results. If there are no more results, the nextToken is null.

Let's look at an example. Let's assume we have 9 SIM cards in our inventory and want to query the ICCIDs of these 9 cards in ascending order. The query is limited to five results, so two queries are necessary to get all results.

Our first query looks like this:

 {
   "variables": {
     "order": { "iccid": "asc" },
     "limit": 5,
     "nextToken": ""
   },
   "query": "query ListSims($order: SimListOrder, $limit: Int!, $nextToken: String) { listSims(order: $order, limit: $limit, nextToken: $nextToken) { items { iccid } nextToken }}"
 }

The result looks like this:

 {
   "data": {
     "listSims": {
       "items": [
         {
           "iccid": "9876543200012345601"
         },
         {
           "iccid": "9876543200012345602"
         },
         {
           "iccid": "9876543200012345603"
         },
         {
           "iccid": "9876543200012345604"
         },
         {
           "iccid": "9876543200012345605"
         }
       ],
       "nextToken": "eyJuZXh0X29mZnNldCI6NX0="
     }
   }
 }

We receive 5 of 9 items. To get the next 5 results we need to set the nextToken eyJuZXh0X29mZnNldCI6NX0= in our next query.

 {
   "variables": {
     "order": { "iccid": "asc" },
     "limit": 5,
     "nextToken": "eyJuZXh0X29mZnNldCI6NX0="
   },
   "query": "query ListSims($order: SimListOrder, $limit: Int!, $nextToken: String) { listSims(order: $order, limit: $limit, nextToken: $nextToken) { items { iccid } nextToken }}"
 }

Our second result looks like this:

{
  "data": {
    "listSims": {
      "items": [
        {
          "iccid": "9876543200012345606"
        },
        {
          "iccid": "9876543200012345607"
        },
        {
          "iccid": "9876543200012345608"
        },
        {
          "iccid": "9876543200012345609"
        }
      ],
      "nextToken": null
    }
  }
}

We got the last 4 items and the nextToken is null which means there are no more items to fetch.

Batch jobs can be started by selecting affected SIM cards through a SIM filter. If no SIM card filter is provided, all SIM cards will be selected for the batch job. Additionally a exclude list can be sent with the request starting a batch job. The exclude list is only applied when no include list is provided. The include list has priority over filter and exclude list.

The maximum size for include and exclude filter is 1000 items.

So the following scenarios will be available:

• create a batch job without SIM filter and no exclude list: all SIM cards of a customer are affected by the batch job
• create a batch job without SIM filter and with exclude list: all SIM cards without the given excluded SIM cards are affected by the batch job
• create a batch job with SIM filter: only the filtered SIM cards are affected by the batch job
• create a batch job with SIM filter and exclude list: all filtered SIM cards without the excluded SIM cards are processed
• create a batch job with include list: only the supplied included SIM cards are affected

Depending on the number of affected SIM cards the batch job may start delayed.

Some examples:

Start a batch job for all SIM cards, changing the monthly data limit to "unlimited":

   {
     "variables": {
       "p1": { "monthly_data_limit": 0 }
     },
     "query": "mutation startBatchJob($p1: BatchJobParametersInput!) {startBatchJob(params: $p1) {batchJobId}}"
   }

Start a batch job for two specific SIM cards, changing the monthly data-, sms mo-, sms mt- and voice-limit to "unlimited":

   {
      "variables": {
        "p2": {
          "includeIccIds": [
            "1234567890123456789",
            "1234567890123456788"
          ],
          "monthly_data_limit": 0,
          "monthly_sms_mo_limit": 0,
          "monthly_sms_mt_limit": 0,
          "monthly_voice_mo_limit": 0
        }
      },
    },
    "query": "mutation startBatchJob($p2: BatchJobParametersInput!) {startBatchJob(params: $p2) {batchJobId}}"
  }

Start a batch job with all SIMs in status "Activated" but exclude 2 SIM cards, changing the voice limit to "unlimited":

  {
    "variables": {
      "p3": {
        "excludeIccIds": [
          "9876543210987654321",
          "9876543210987654322"
        ],
        "simFilter": {
          "statusid": {
            "in": [
              2
            ]
          }
        },
        "monthly_voice_mo_limit": 0
      }
    },
    "query": "mutation startBatchJob($p3: BatchJobParametersInput!) {startBatchJob(params: $p3) {batchJobId}}"
  }

The following table shows a list of the possible error codes when a batch job is executed:

Error code	Description
1	StatusID has not been changed because it was set already to the desired one
2	Status could not be changed at provider
3	General error while setting SIM status
4	Status transition not allowed
100	Custom field 1 has not been changed because it was already set to the desired one
101	Error writing new custom field 1 value to database
102	General error while setting custom field 1
200	Data limit not changed because it was already set to the desired one
201	General error while setting data limit
300	SMS MO Limit not changed because it was already set to the desired one
301	General error while setting SMS MO limit
400	SMS MT Limit not changed because it was already set to the desired one
401	General error while setting SMS MT limit
500	Voice MO Limit has not changed because it was already set to the desired one
501	General error while setting voice MO limit
600	End customer label not been changed because it was already set to the desired one
601	Error writing new end customer label to database
602	General error while writing end customer label
700	IMEI lock not changed because already set to desired one
701	General error while writing IMEI lock