Hi All,
When designing REST API for WSO2 Identity Server we have identified three
main use cases for using the links in the response. And have
discussed possible ways to use links for representing those response
content.
1) Representing a relationship or representing the next action.
Here the relationship is something as there can be a resource
type that has a collection of resources. Refer to the following example.
{
- "resourceId":"638ed840-7319-400f-89a0-34cd51f6295b",
- "tenantDomain":"wso2.com",
- "resourceName":"EmailPublisher",
- "resourceType":"Publisher",
- "lastModified":"2019-10-09T14:26:54Z",
- "created":"2019-10-09T14:26:14Z",
- "resources":[
1. {
- "links":[
1. {
- "href":
"/t/{tenant-domain}/resource/Publisher/EmailPublisher",
- "rel":"resource"
}
]
}
]
}
Also, this can also relate to the next action. Refer to the example below.
{
- "code":"PWR-02002",
- "message":"Password recovery information sent externally",
- "notificationChannel":"EXTERNAL",
- "resendCode":"12345-45678-6789098-8765",
- "links":[
1. {
- "rel":"next",
- "href":"api/identity/recovery/v1/password/confirm",
- "type":"POST"
},
2. {
- "rel":"resend",
- "href":"api/identity/recovery/v1/password/resend",
- "type":"POST"
}
]
}
2) Representing a fully detailed description of a resource.
There can be scenarios that we give basic limited information about a
resource and provide a link to get the fully qualified details using a
link. Refer to the following example.
{
- "Service Provider Name":"Travelocity",
- "Service Provider ID":"SP00001",
- "self":"api/identity/serviceproviders/sp00001"
}
Here the location denoted in the self will give the full details of the SP.
3) Representing a path of a specific resource.
The response should indicate the specific location of the resource using a
name that is related to that specific context. Please refer to the
following example.
{
- "resourceId":"638ed840-7319-400f-89a0-34cd51f6295b",
- "tenantDomain":"wso2.com",
- "resourceName":"EmailPublisher",
- "resourceType":"Publisher",
- "lastModified":"2019-10-09T14:26:54Z",
- "created":"2019-10-09T14:26:14Z",
- "attributes":[
1. {
- "key":"from",
- "value":"[email protected]"
},
2. {
- "key":"password",
- "value":"xxxxx"
},
3. {
- "key":"user",
- "value":"wso2iam"
}
],
- "files":[
1. {
- "name":"EmailPublisher",
- "file":
"/t/{tenant-domain}/resource/abc/EmailPublisher/06130a18-8a9f-43d2-812b-eafc69ff9886"
}
]
}
Here the response is representing a resource that has files as its
property. File and the resource have a composition type of relationship,
using the given location user can get the specific file.
Please let us know your thoughts on this.
Thanks and Regards
*Buddhima Udaranga*|Software Engineer| WSO2 Inc. <http://wso2.com/>
(M)+94 714742094 | (E) [email protected]
<https://wso2.com/signature>
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
