Hypermedia Links
What Can I Do Next?
The RESTful nature of the uShip API (v2) makes it largely focused around using hypermedia concepts to provide context when retrieving resources.
With this design in mind, a client's goal should be programmatically learning the links and...
Not hard code URIs or parameters in your applications.
Build your app logic so that it depends on the existence of links to provide the URI from the href
attribute field rather than hardcoding a fixed URI. With this approach, you rapidly adapt to new URIs and rely on the API for the logic which indicates the user's permission to perform those actions. This approach also facilitates better version management as URI's might change when incrementing versions.
How?
If the user has permissions, the related hypermedia links appear to suggest what action can be taken. For example, a mobile developer uses these links to show the button on the UI associated with the action. We recommend and encourage developers to focus on the rel
and title
fields to relate links to specific actions.
Example
This example shows the data hierarchy that appears in the JSON response body. The following excerpt is part of retrieving a newly created saved search.
JSON Link Array Sample
... "links": [ { "rel": "List", "verb": "GET", "href": "/v2/savedSearches", "title": "savedSearches" }, { "rel": "Create", "verb": "POST", "href": "/v2/search", "title": "search" }, { "rel": "List", "verb": "GET", "href": "/v2/savedSearches/f31ff4b0-437c-41bf-ab9d-79c67f6407c2/results", "title": "results" } ]...
Reference
Link Wrapper
Field | Type | Description | Sample Valid Value |
links |
Array | Wrapper for the hypermedia links and link field data set that create the desired object. A hypermedia link suggests what a user can do next in the relevant context or contexts. The fields in this table comprise the data set. | - |
Array Object Fields
Field | Type | Description | Sample Valid Value |
rel |
String | Describes which object the link relates to such as the ability to complete a function in a certain context. This reference is one of the possible actions. All possible rel values are in the table below. |
"Create" |
|
String |
REST verb associated with the possible action.
|
"POST" |
|
String |
Hypertext reference attribute that specifies the URL of the page link destination. This reference link suggests what actions are possible. The href link reference here would always have a valid listing ID in place of {listingID}. Examples /v2/listings/{listingId}/bids /v2/listings/980456625/bids |
|
title |
String | Descriptive name of the possible action. |
"bidAtNamedPrice" |
Valid "rel" Values
The rel
value describes the relationship of the provided link to the retrieved resource (title
).
Value | Description |
Create | Create a new item. |
Delete | Remove or delete a related item. |
Item | A related resource containing one item. |
List | A list or array of related items. |
Self | The source link where the document is stored. |
Update | Updated a related item. |
Valid Hypertext or Link Combinations
Example 1
From the Saved Search API. This array of links explains what can be done next.
Link | Possible Action |
"rel": "List", "verb": "GET", "href": "/v2/savedSearches", "title": "savedSearches" |
Retrieve a list of saved searches for the authenticated user. See Saved Search for details. |
"rel": "Create", "verb": "POST", "href": "/v2/search", "title": "search" |
Create a new search. See Saved Search for details. |
"rel": "List", "verb": GET", "href": "/v2/savedSearches/{GUID}/results", "title": "results" |
Specify the search ID for the saved search result to retrieve. The href link reference here would always have a valid GUID in place of {GUID}. Example "/v2/savedSearches/fe7ca848-22c6-4b6b-ac3a-a5c556bea4d6/results" |
Example 2
From GET https://api.uship.com/v2/listing/{listingID}
Link | Possible Action |
"rel": "List", "verb": "GET", "href": "/v2/listings/{listingID}/conversations", "title": "listingconversations" |
Retrieve a list of active listing question and answers for permitted users. See Listings Conversations for details. The href link reference here would always have a valid listing ID in place of {listingID}. Example "/v2/listings/980456625/conversations |
Pagination
Where available and supported, a resource returns a hypermedia link for the client to go to the next page of results for responses that return collections with a large number of results.
The default page size is 25 entries.
"links": [{ "rel": "Next", "verb": "GET", "href": "/v2/listings?userType=ServiceProvider&access_token={token}&$skip=25", "title": "listings" }]
Docs Navigation
- Get Started
- FAQ's
- Authentication
- Authorization Code
- Resource Owner Password Credentials
- Client Credentials
- Hypermedia Links
- Error Handling
- Design Guide
- API Reference
- Object Reference