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"

verb

 String

REST verb associated with the possible action.

  • GET - Retrieve an object or array of objects.
  • PUT - Update an existing object or array of objects.
  • POST - Create a new instance of an object or array of objects.
  • DELETE - Remove an object or array of objects.

"POST"

href

 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"
    }]

version 106 as of 2 years ago by uShip