Short URLs API
- List short URLs
- Get a single short URL
- Get a QR code image
- Create a short URL
- Update a short URL
- Fields
- Reserving multiple short URLs
List short URLs
List all short URLs for an account:
GET /short_urls
Response
Status: 200 OK
[
{
"id": 68875,
"short_url": "https://itrp.io/XaeLN9",
"uri": "itrp:self_service?ci_id=31429",
"created_at": "2015-11-19T14:45:52-08:00",
"updated_at": "2015-11-19T14:45:52-08:00"
},
{
"id": 68874,
"short_url": "https://itrp.io/EZCV9H",
"uri": "itrp:self_service?request_template_id=5823",
"created_at": "2015-11-19T14:45:52-08:00",
"updated_at": "2015-11-19T14:45:52-08:00"
},
{
"id": 68876,
"short_url": "https://itrp.io/77gegn",
"uri": "https://r-service.tech",
"created_at": "2015-11-19T14:47:33-08:00",
"updated_at": "2015-11-19T14:47:33-08:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of short URLs.
Collection Fields
By default the following fields will appear in collections of short URLs:
id
sourceID
name
group
rule_set
reference
created_at
updated_at
Obtain a different set of fields using the ?fields=parameter.
Filtering
Filtering is available for the following fields:
id
created_at
updated_at
Sorting
By default a collection of short URLs is sorted descending by id
.
Get a single short URL
GET /short_urls/:id
Response
Status: 200 OK
{
"id": 68875,
"short_url": "https://itrp.io/XaeLN9",
"uri": "itrp:self_service?ci_id=31429",
"created_at": "2015-11-19T14:45:52-08:00",
"updated_at": "2015-11-19T14:45:52-08:00"
}
The response contains these fields.
Get a QR code image
GET /short_urls/:short_url_token/qrcode
This returns a chunked PNG.
The following HTML example shows how the QR code of a short URL can be included dynamically in a web page (place the HTML between angle brackets):
img src="https://api.r-service.tech/v1/short_urls/dUD3Rb/qrcode"
The example below shows how the QR code of a short URL can be downloaded as a PNG image file with the name filename.png
:
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X GET \ https://api.r-service.tech/v1/short_urls/dUD3Rb/qrcode > filename.png
Create a short URL
POST /short_urls
When creating a new short URL these fields are available.
Response
Status: 201 Created
{
"id": "...",
"...": "..."
}
The response contains all fields of the created short URL and is similar to the response in Get a single short URL
The following are two simple examples for creating a short URL using CURL:
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X POST \ https://api.r-service.tech/short_urls?twitter_name=R-Service
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X POST \ https://api.r-service.tech/short_urls?plain_text=hello%20world%21
Update a short URL
PATCH /short_urls/:id
When updating a short URL these fields are available.
Response
Status: 200 OK
{
"id": "...",
"...": "..."
}
The response contains all fields of the updated short URL and is similar to the response in Get a single short URL
Fields
- created_at
- Readonly datetime — The date and time at which the short URL was created.
- id
- Readonly integer — The unique ID of the short URL.
- short_url
- Readonly string (max 255) — The Short Url field contains the automatically generated website address that is forwarded to URI.
- uri
- Optional string (max 4096) — The URI field contains the uniform resource identifier to which the short URL is forwarded.
- updated_at
- Readonly datetime — The date and time of the last update of the short URL. If the short URL has no updates it contains the
created_at
value.
Additional fields
The following are additional fields that can be used to automatically generate the uri
value of a short URL:
- ci_id
- Optional reference to Configuration Item — The Configuration item field is used to select the CI for which a request is to be registered in R-Service Self Service when the short URL is used.
- email_body
- Optional string — The Body field is used to enter the body of the email that is to be generated when the short URL is used. This field should only be used in conjunction with the ‘email_to’ and ‘email_subject’ fields.
- email_subject
- Optional string — The Subject field is used to enter the subject of the email that is to be generated when the short URL is used. This field should only be used in conjunction with the ‘email_to’ and ‘email_body’ fields.
- email_to
- Optional string — The To field is used to enter the email address of the recipient of the email that is to be generated when the short URL is used. This field should only be used in conjunction with the ‘email_subject’ and ‘email_body’ fields.
- geo_latitude
- Optional string — The Latitude field is used to enter the latitude coordinate of the location for which a map should be opened when the short URL is used. This field should only be used in conjunction with the ‘geo_longitude’ field.
- geo_longitude
- Optional string — The Longitude field is used to enter the longitude coordinate of the location for which a map should be opened when the short URL is used. This field should only be used in conjunction with the ‘geo_latitude’ field.
- knowledge_article_id
- Optional reference to Knowledge Article — The Knowledge Article field is used to select the knowledge article which instructions need to be displayed when the short URL is used in R-Service Self Service.
- map_address
- Optional string — The Address field is used to enter the address (or only the city or country) for which a map should be opened when the short URL is used.
- plain_text
- Optional string — The Plain text field is used to enter the text that should be displayed when the short URL is used.
- request_template_id
- Optional reference to Request Template — The Request template field is used to select the request template that is to be applied to each new request that is opened when in R-Service Self Service when the short URL is used.
- skype_name
- Optional string — The Skype username field is used to enter the Skype name that is to be called when the short URL is used.
- sms_tel
- Optional string — The Telephone number field is used to enter the telephone number of the recipient of the SMS message that is to be generated when the short URL is used. This field should only be used in conjunction with the ‘sms_body’ field.
- sms_body
- Optional string — The SMS message field is used to enter the text of the SMS message that is to be generated when the short URL is used. This field should only be used in conjunction with the ‘sms_tel’ field.
- tel
- Optional string — The Telephone number field is used to enter the telephone number that is to be called when the short URL is used.
- tweet
- Optional string — The Tweet field is used to enter the text of the Twitter tweet that is to be generated when the short URL is used.
- twitter_name
- Optional string — The Twitter username field is used to enter the name of the Twitter user whose Twitter feed is to be opened when the short URL is used.
- uri
- Optional string — The URI field is used to enter the uniform resource identifier to which the short URL is to forward when it is used.
- website_url
- Optional string — The Website URL field is used to enter the uniform resource locator of a website to which the short URL is to forward when it is used.
Reserving multiple short URLs
Multiple short URLs can be generated in bulk using the following API call:
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X POST \ https://api.r-service.tech/v1/short_urls/reserve?amount=1000
The example above generates 1000 short URLs without a URI. Once these short URLs have been generated, they are reserved for the account. These reserved URLs can then be exported and used to order QR codes or NFC tags in bulk.
The response from the API is a token that acts as the unique identifier for the job. This token can be used to retrieve information about the progress of the job.
Status: 200 OK
{
"token": "69ea3...1e7133"
}
It is important to note that the API user needs to have the Configuration Manager or Account Administrator role to be able to reserve short URLs using the API. In the example above, the API user specifically needs to have the Configuration Manager or Account Administrator role of the account which id
is “wdc”. The Authentication section describes how the api-token
of the API user can be found.
In the example above it would not be necessary to specify -H "X-4me-Account: wdc"
provided that the Person record of the API user is registered in the account which id
is “wdc”.
Parameter
The following parameter is supported:
- amount
- Required integer — The number of short URLs that are to be generated for the account. A maximum of 10,000 can be reserved at any time per account.
Job progress
The reservation process runs as a background job. It is possible to check the progress of a job automatically using the token received from the job response.
Five minutes after the job is completed, the progress information is not available anymore through the API.
Example:
$ curl -H "Authorization: Bearer <oauth-token>" \ -H "X-4me-Account: wdc" \ -X GET https://api.r-service.tech/v1/short_urls/reserve/69ea3...1e7133
Depending on the state of the job, one of the following responses is returned:
Queued
Status: 200 OK
{
"state": "queued"
}
The job is scheduled for execution.
Processing
Status: 200 OK
{
"state": "processing",
"message": "Reserved 700 Short URLs"
}
The job is being processed.
Done
Status: 200 OK
{
"state": "done"
}
The job is complete.
Note that if the process was able to recover from an error, the state done
is returned. The response contains the state error
as outlined below only when an error prevented the job from completing.
Error
Status: 200 OK
{
"state": "error",
"message": "..."
}
The job was aborted prematurely because of an unrecoverable error. A short description of the issue is provided in the message
attribute. More detailed information can be found in the Job Log. Errors should always be investigated.
Not Found
Status: 404 Not Found
The job was completed more than 5 minutes ago, so no progress information is available anymore. Information on the completed job can still be found in the Job Log.
Job log
Each job that is complete (with or without errors) is entered in the System Logs of the Settings console. Log into R-Service as an Account Administrator and go to Settings => System Logs and select the Job Log view to see them all.
The Level
column will contain Fatal
in case an error has occurred.