Examples of Configuring REST Resources Based on JSON API

You can create a REST V2 resource and make the resource as JSON API compliant. Integration Server automatically creates all the services, document types, and JSON API based URL templates for the REST V2 resource along with the applicable input and output signatures.

This following example creates two REST V2 resources as Article and Author and both the resources are JSON API compliant. You can create the attributes for Article ensuring that one attribute, for example, id is set as unique identifier. Integration Server generates the REST URL templates based on this unique identifier. For more information about creating a JSON API compliant REST V2 resource and adding new attributes, see Creating a REST V2 Resource.

Integration Server generates the following URL templates according to the JSON API specifications. You can check these URLs and modify them under the Resource Configuration tab. For example,

/Article GET

/Article/{id} GET

/Article POST

/Article/{id} DELETE

/Article/{id} PATCH

You can assign a relationship between Article and Author by setting the attribute type as Resource. Integration Server generates the following relationship URL templates according to the JSON API specification:

/Article/{id}/relationships/Author GET

/Article/{id}/relationships/Author PATCH

/Article/{id}/relationships/Author DELETE

/Article/{id}/relationships/Author POST

Once you create the assets, the package viewer might have the following folder structure as viewed from Software AG Designer.

For more information on defining REST V2 resource attributes and assigning relationships, see Defining a REST V2 Resource Attribute.

For more information about checking these REST V2 URLs and modifying them, see Defining a REST V2 Resource Operation.

Request and Response Formats for JSON API Resource

This section lists sample request and response formats for two JSON API resources, Article and Author.

Get all Article records

Request format: http://host:port/rad/namespace_of_rad/Article with Accept=application/vnd.api+json

Response format:

{
"data": [
{
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
},
"links": {
"self": "http://host
:port/rad/namespace/Article/1/
relationships/Author",
"related": "http://host:port/
rad/namespace/Article/1/Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
}
},
{
"id": "3",
"type": "Article",
"attributes": {
"blogname": "gmail"
},
"relationships": {
"Author": {
"data": {
"id": "4",
"type": "Author"
},
"links": {
"self": "http://host:port/rad/namespace/
Article/3/relationships/Author",
"related": "http://host:port/rad/namespace/
Article/3/Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/3"
}
}
],
"links": {
"self": "http://host:port/rad/namespace/Article"
},
"meta": {
"total-records": "2"
}
}

Get single Article record

Request format: http://host:port/rad/namespace_of_rad/Article/1 with Accept=application/vnd.api+json

Response format:

{
"data": {
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
},
"links": {
"self": "http://host:port/rad/namespace/Article/1/
relationships/Author",
"related": "http://host:port/rad/namespace/Article/1/
Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
},
"meta": {
"total-records": "1"
}
}

Post an Article record

Request format: http://host:port/rad/namespace_of_rad/Article with Content-Type=application/vnd.api+json and Accept=application/vnd.api+json and the body as

{
"data": {
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
}
}
}
}

}

Response format: Response status is 204. If UID is set or any response code is set then the response is,

Delete an Article record

Request format: http://host:port/rad/namespace_of_rad/Article/1 with Accept=application/vnd.api+json

Response format: Response status is 200. If user sets output values then the response is,

Patch a record

Request format: http://host:port/rad/namespace_of_rad/Article/1 with Content-Type=application/vnd.api+json and Accept=application/vnd.api+json with body as

{
"data": {
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook",
"id": "1"

},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
}
}
}
}

}

Response format: Response status is 200. If user sets output values then the response is,

Get all related data

Request format: http://host:port/rad/namespace_of_rad/Article/1/relationships/Author

Response format:

{
"data": [
{
"id": "2",
"type": "Author",
"attributes": {
"name": "social"
},
}
],
"links": {
"self": "http://host:port/rad/namespace/Article/1/relationships/Author"
"related": "http://host:port/rad/namespace/Article/1/Author"
},
"meta": {
"total-records": "1"
}
}

Update an Author record

Request format: http://host:port/rad/namespace_of_rad/Article/1/Author with body as

{
"data":
{
"id": "2",
"type": "Author",
"attributes": {
"name": "social"
}
}

}

Response format: Response status is 200. If user sets output values then the response is,

{
"data": {
"id": "2",
"type": "Author",
"attributes": {
"name": "social"
},
},
"links": {
"self": "http://host:port/rad/namespace/Article/1/relationship/Author"
"related": "http://host:port/rad/namespace/Article/1/Author"
},
"meta": {
"total-records": "1"
}
}

Delete an Author record

Request format: http://host:port/rad/namespace_of_rad/Article/1/Author with Accept=application/vnd.api+json

Response format: Response status is 200. If user sets output values then the response is,

Include an Author record

Request format: http://host:port/rad/namespace_of_rad/Article?include=Author

Response format:

{
"data": [
{
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
},
"links": {
"self": "http://host:port/rad/namespace/Article/1/
relationships/Author",
"related": "http://host:port/rad/namespace/Article/1/
Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
}
},
{
"id": "3",
"type": "Article",
"attributes": {
"blogname": "gmail"
},
"relationships": {
"Author": {
"data": {
"id": "4",
"type": "Author"
},
"links": {
"self": "http://host:port/rad/namespace/Article/3/
relationships/Author",
"related": "http://host:port/rad/namespace/Article/3/
Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/3"
}
}
],
"included": [
{
"id": "2",
"type": "Author",
"attributes": {
"name": "social"
},
"relationships": {},
"links": {
"self": "http://host:port/rad/namespace/Author/2"
}
},
{
"id": "4",
"type": "Author",
"attributes": {
"name": "mail"
},
"relationships": {},
"links": {
"self": "http://host:port/rad/namespace/Author/4"
}
}
],
"links": {
"self": "http://host:port/rad/namespace/Article"
},
"meta": {
"total-records": "2"
}
}

Sparse field sets

Request format: http://host:port/rad/namespace_of_rad/Article/1?fields=blogname,id

Response format:

{
"data": {
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook",
"id": "1"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
},
"links": {
"self": "http://host:port/rad/namespace/Article/1/
relationships/Author",
"related": "http://host:port/rad/namespace/Article/1/
Author"
}
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
}
},
"links": {
"self": "http://host:port/rad/namespace/Article/1"
},
"meta": {
"total-records": "1"
}
}

Sort a record

Request format: http://host:port/rad/namespace_of_rad/Article?fields=id,blogname&sort=-id

Response format:

{
"data": [

{
"id": "3",
"type": "Article",
"attributes": {
"blogname": "gmail",
"id": "3"
},
"relationships": {
"Author": {
"data": {
"id": "4",
"type": "Author"
}
}
}
},
{
"id": "1",
"type": "Article",
"attributes": {
"blogname": "facebook",
"id": "1"
},
"relationships": {
"Author": {
"data": {
"id": "2",
"type": "Author"
}
}
}
}
],
"links": {
"self": "http://host:port/rad/namespace/Article"
},
"meta": {
"total-records": "2"
}
}

Filter a record

Request format: http://host:port/rad/namespace_of_rad/Article?filter[id][EQ]='xyz'

Response format: In pipeline $filter value is set so user needs to implement the service according to the filter.

Page number and page limit of a record

Request format: http://host:port/rad/namespace_of_rad/Article?page[number]=0&page[limit]=1

Response format:

Processing the Errors

The output signature of a service might have an error structure associated with it. The error object contains multiple entities that provide additional information about problems encountered while performing an operation. An error object contains the following entities:

id: a unique identifier for this particular occurrence of the problem.

links: a link object containing the following members:

about: a link that leads to further details about this particular occurrence of the problem.

status: the HTTP status code applicable to this problem, expressed as a string value.

code: an application-specific error code, expressed as a string value.

title: a short summary of the problem that should not change from occurrence to occurrence of the problem.

detail: an explanation specific to this occurrence of the problem.

source: an object containing references to the source of the error, optionally including any of the following members:

pointer: a JSON Pointer to the associated entity in the request document.

parameter: a string indicating which URL query parameter caused the error.

meta: a meta object containing non-standard meta-information about the error.