Changes for page API

Last modified by David Persson on 2022/08/11 10:43
From version 3.1
edited by David Persson
on 2019/12/04 09:49
To version 4.1
edited by Mikael Widström
on 2020/01/09 10:01
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.dap
1 +xwiki:XWiki.mak
Content
... ... @@ -15,7 +15,59 @@
15 15  
16 16  == Introduction ==
17 17  
18 +The resources follows rest-full patterns including hyper-media links, we use hyper-media and backend-for-frontend principles to impose business rules and reduce duplication of business logic in front-and back-end.
18 18  
20 +=== Basic resources ===
21 +
22 +//Basic resources uses the common HTTP patterns for GET, POST, PUT, PATCH, DELETE.//
23 +
24 +* Requests __**without**__ specific resource identifier - f.ex. /ledger/credit-account/v1/XXX/accounts
25 +** HTTP GET - Returns a list of resources
26 +** HTTP POST - Creates a new resource
27 +* Requests __**with**__ specific //__resource identifier__// - f.ex. /ledger/credit-account/v1/XXX/accounts///__1234568__//
28 +** HTTP GET - Returns a specific resource
29 +** HTTP PUT - Updates a specific resource
30 +** HTTP PATCH - Partially updates a specific resource
31 +** HTTP DELETE - Deletes a specific resource
32 +
33 +=== Operation resources ===
34 +
35 +//Functions that cannot be mapped directly to resources are called "Operation Resources" they only support HTTP POST//.
36 +
37 +* Requests __**without**__ specific resource identifier operates on the list
38 +** HTTP POST - f.ex. /ledger/credit-account/v1/XXX/accounts/generate-summary - Generates a summary
39 +* Requests __**with**__ specific resource identifier operates on a resource
40 +** HTTP POST - f.ex. /ledger/credit-account/v1/XXX/accounts/1234568/initiates-termination - Starts termination of an account
41 +
42 +
43 +=== Hyper-media response ===
44 +
45 +The response will include a list of operations that is possible to perform. Below is an example when a HTTP-GET Request is issued to retrieve information on an account. The response includes an "operations" property with a list of possible possible operations. The list of operations returned only contains business-rule and access-control validated operations. In the sample below the only allowed way to interact with the resource is to issue "patch" requests to modify fields. Different states as well as access permissions on the resource affect which operations are returned.
46 +
47 +
48 +{{code language="javascript" title="**Hyper-media response sample**"}}
49 +{
50 + "@id": "/ledger/credit-account/v1/501/accounts/1234567", //Resource identifier
51 + //Fields...
52 + "operations" : [
53 + {
54 + "rel" : "partial-update",
55 + "method" : "patch",
56 + "href" : "/ledger/credit-account-onboardings/v1/501/accounts/123456"
57 + }
58 + ]
59 +}
60 +{{/code}}
61 +
62 +
63 +(% class="box successmessage" %)
64 +(((
65 +**Tip:** As an implementing consumer of the api **operations** should be taken into consideration rather than trying to determine possible operation based on other basic resource properties. By following this tip we: minimize duplication of business logic, simplify maintenance when business rules change, have a clear separation of concerns.
66 +)))
67 +
68 +(% class="wikigeneratedid" %)
69 +== ==
70 +
19 19  == Problems ==
20 20  
21 21  If an error occur or any validation failed, a "problem" response will be returned.