{"swagger":"2.0","info":{"title":"A Simple Banking API HATEOAS HAL Sample","version":"0.0.1","description":"This \"Simple Banking API Sample\" serves to exemplify a way of using HATEOAS in the form of HAL in the API in and easy and intuitive way. Furthermore it points to elaborated examples and what would be nice to have supported in a better way in the REST implementations and possibly in Swagger in order have an easy way to use the full potential of HATEOAS in the form of HAL and services.\n\n## API Description\nThis API show a very simple set of resources that emulates three micro-services which are: account, payment and Person. The Idea is to create everything as one large single Swagger file and decompose that into some sections: e.g. a general section,  a capabilities section, where the various API capabilities can be imported etc.\n## General Principles\nA semantic REST API is using and thus also HATEOAS in form of the hal specification. The API can be versioned at the structural level by means of a HTTP Header and at the content level in each endpoint by means of the content-type.\n## HTTP Headers used\nA number os headers are used.\n* `X-Log-Token` for correlating a number activities between service and consumers of the service.\n* `X-Client-Version` for identification of a client version and its contract.\n* `X-Service-Generation` to signal a non-current structure of the API (saves known redirects from a client perspective)\n* `Accept` is used to signal what content the consumer wished and the version and projection can be specified. \n### Correlation between service (Server) and consumer (Client)\nA `X-Log-Token` header is used to give a client the opportunity to find a number of calls and activities related to calls belonging to that context. If the client includes a `X-Log-Token` header and a value associated with that, the value will be extended with a timetick initially to ensure uniqueness. The original `X-Log-Token` is returned in every response from the service, the client must include the unique token received in the response in the  following requests if the correlation is still what the client wants. If the client does not include a `X-Log-Token` the service creates a unique token and returns that in the response and the client can use that.  \n### Client Identifier\nThe `X-Client-Version` header is used for identification of the client version and is required in order for a client to successfully operate on resources. The version in according to semver-org\n### Versions\nThere exists two major forms of versioning: one is related to the structure of the API, the other is related to the contents in each endpoint in the API.\nThe two different aspects are handled in each their dedicated fashion. \nThe `X-Service-Generation` HTTP header is used for signalling the version of the API structure instead of having the version as a part of the baseURL. \nThe content-type includes version information and is returned in every response from the service. The content-type can do that is a couple of ways: \n\n  * using `\"_links\": { \"href\": \"...\"}` with no `\"type\"` will point to the newest and current content at the referenced endpoint.\n\n  * using  `\"_links\": { \"href\": \"...\", \"type\": \"application/hal+json;v=1\"}` with `\"type\"` will point to the version listed and in this case that is the version 1 at the referenced endpoint.\n\n  The client must know if a problem has occurred in a situation, where the contents from a service endpoint was updated in a way that this particular client could not cope with and therefore it must know what version works and this the hal specification can be used decorate the `\"_links\":` object with the version of the content that it understands. That lets the client include the understandable content-type as defined in `\"_links\":` and include that as the value of the \"Accept\" header.\n  An example of such client side decorated response from a server, where the default and newest content-type are \"overwritten\" by the type for the users.\n\n\n    {\n      \"label\": \"Budget Account\",\n      \"currency\": \"DKK\",\n      ...\n      \"_links\": {\n        \"transactions\": [{\n            \"href\": \"accounts/1234-567890/transactions/987654321\"\n          }, {\n            \"href\": \"accounts/1234-567890/transactions/987654322\"\n          }, {\n            \"href\": \"accounts/1234-567890/transactions/987654323\"\n          }\n        ],\n        \"users\": {\n          \"primary\": {\n            \"href\": \"users/hans-b-hansen-13-09-1234\",\n            \"type\": \"application/hal+json;v=1\"\n          },\n          \"coUsers\": [{\n              \"href\": \"users/frederikke-b-hansen-16-07-6789\",\n              \"type\": \"application/hal+json;v=1\"\n            },{\n              \"href\": \"users/ulla-b-hansen-23-03-4567\",\n              \"type\": \"application/hal+json;v=1\"\n            }]\n        }\n      }\n    }\n\nIf a projection (a given view on e.g. the user is needed) that may be included in the content-type as well, if a matching producer is available in the service that will be used. the version is referring to the structures and contents of the json response from a given endpoint. It is not the historical state of a user object. Examples of the versions of content by value in the `Accept` header below:\n* `\"application/hal+json;concept=user;v=1\"` for the complete user json in hal format\n* `\"application/hal+json;concept=user-basic;v=1\"` for the basic user information in hal json format\n* `\"application/hal+json;concept=user-basic\"` for the newest version of basic user information in hal format\n* `\"application/hal+json\"` for the newest version of user information in hal format\n\nIt is possible to express the same without using the parameters as shown above using - although less elegant and less HTTPish:\n\n* `\"application/hal+json+user+1\"` for the complete user json in hal format\n* `\"application/hal+json+user-basic+1\"` for the basic user information in hal json format\n* `\"application/hal+json+user-basic\"` for the newest version of basic user information in hal format\n## API Capability Set\nIn every API of a certain size a number of capabilities are used. These capabilities consists of a particular set of functionality. This functionality can be divided into the following capabilities:\n\n\n\n     Selection:    `select` \n                   - selecting objects by attribute value(s) for response\n\n     Sorting:      `sort` \n                   - sorts objects descending and ascending by \n                     attribute(s) for response\n\n     Temporal:     `interval` \n                   - limits relevant objects in desired response\n                     to be within a certain time frame\n\n     Pagination:   `elements` \n                    - specifies the elements in a range desired \n                      to be in response\n\n     Filtering:   `filter` \n                   - ask for exclusion or inclusion of particular\n                     attributes or objects in response\n\n     Composition: `embed` \n                  - ask for the inclusion of \"related\" objects and \n                    projection into the response.\n\n\nThese capabilities may be applied individually to endpoints in APIs. The user of the API endpoint can see what capability/ies is/are supported at each endpoint by looking at the for tags like select, sort, paginate etc. The Swagger tags are used here to achieve an easy way to show the capabilities in each endpoint as can be seen further down in the Swagger specification.\nAnother perspective that is often seen in APIs is the use of technical keys (potentially UUIDs) which are semantically poor, but often seen as a necessity for sensitive keys such as social security numbers. In order to avoid having these sensitive information leaked to logs and other places, there is a need for bringing these keys into the body of a request and a non-sensitive key is going to help. The problem with an UUID'ish key is that the developer experience is not optimal. Therefore it would be a nice thing to get some form of consensus on a derived capability like :\n\n      Sensitive Semantic ID deconstruction \n      - generation of non-sensitive semantic key for objects that has a sensitive\n        semantical key in the form of something that has a better developer\n        experience than e.g. UUIDs can offer.\n\n### Selection API Capability\nSelection by criteria(s) is done using a Query Parameter called `select`. \n\n    The syntax is: select=\"<attribute>::<value>|<atribute>::<value>|...\"\n\n\nThe usage can be exemplified by e.g. asking for accounts having a balance equal to 100. Currency is omitted here on purpose.\n\n#### The concrete url would look like: \n\n     <https://banking.services.sample-bank.dk/\n              accounts?select=\"balance::100\">\n     \n     \"balance::100\"\n     which returns accounts having a exact balance of 100.\n\n#### Another example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts?select=\"balance::100+|balance::1000-\">\n    \n    select=\"balance::100+|balance::1000-\"\n    which returns accounts having a balance between 100 and 1000 (both inclusive).\n    \n#### Yet another example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts?select=\"no::123456789+|no::234567890\">\n    \n    select=\"no::123456789+|no::234567890\"\n    which returns the to accounts having account numbers \"123456789\" and \"234567890\" and thus it works as a way to select certain objects, in this case based on the semantic key for an account which is the number of that account.\n\n### Sorting API Capability\nSorting is done using a `sort` Query Parameter. Sorting can be done ascending (default) or descending\n\n      The syntax is: sort=\"<attribute>+/-|<attribute>+/-|...\"\n      and is equivalent to: sort=\"<attribute>::+/-|<attribute>::+/-|...\"\n\nThe usage can be exemplified as an\n#### Example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts?sort=balance>\n    which returns an ascending set of accounts sorted by balance\n\n\n#### Another example is: \n\n    <https://banking.services.sample-bank.dk/\n             accounts?select=balance|lastUpdate->\n    which returns a set of account sorted descending by\n    lastUpdate and ascending by balance. \n\n### Temporal API Capability\nTemporal aspects are handled using the `interval` Query Parameter.\n\n\n      The syntax is: interval=\"<now/from/to/at/::+/-/#d/#/now>|\n                               <now/from/to/at/::+/-/#d/#>\"\n\n#### Example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789/transactions?interval=\"from::-14d|to::now\">\n    which returns the transactions from a specific account within the last 14 days\n\n#### Another example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789/transactions?interval=\"from::1476449846|to::now\">\n    \n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789/transactions?interval=\"from::1476449846\">\n    \n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789/transactions?interval=\"at::1476449846\">\n    \n    The latter three returns the transactions from a specific account \n    within the last day assuming now is friday the. \n    14th of October 2016 UTC time.\n\n### Pagination API Capability \nPagination of responses is obtained by using the Query parameter `elements`. The Query Parameter `elements` signals the initial element and the last element that is desired to be part of the response.\n\n    The syntax is: elements=\"<startingFrom>|<endingAt>\" both inclusive.\n\n#### Example:\n\n     <https://banking.services.sample-bank.dk/\n              accounts/1234-56789/transactions?elements=\"10|30\"> \n     which returns element 10 as the first entry in the json \n     response and element 30 as the last entry in the response.\n\n\nA maximum element size is defined here max size is 500 elements\n### Filtering API Capability\nThe Query parameters `filter` is used for signalling to the server that a dynamic projection is desired as the response from the service. The service is not obliged to be able to do that, but may return the standard projection of the objects given for that concrete endpoint. This can be used for discovery of what projections service consumers would like to have and help evolving the API to stay relevant and aligned with the consumers use of the service.\n\n    The syntax is: filter=\"<attribute>::+/-|<attribute>::+/-\" \n    + means include only\n    - means exclude only\n    \n\n\n#### Example:    \n\n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789?filter=\"balance::-|name::-\"> \n    which ideally returns a account object in the response without balance \n    and name attributes.\n    The service may however in the event that this is not supported,\n    choose to return a complete object and not this sparse dynamic view. \n\n\n#### Example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789?filter=\"balance::+|name::+\">\n    which ideally returns a account object in the response with only balance\n    and name attributes.\n    The service may however in the event that this is not supported,\n    choose to return a complete object and not this sparse dynamic view. \n\n### Composition  API Capability \nComposition is about enabling the consumers of services, the Query Parameter `embed` is used to signal to the service that the consumer would like to have a certain assumed related object included as a part of the response if possible.\n\n    The syntax is: embed=\"<concept>::<projection>|<concept>::<projection>|...\" \n    \n    \n#### Example:\n\n    <https://banking.services.sample-bank.dk/\n             accounts/1234-56789?embed=\"transaction::list|owner::sparse\"\n    \n    embed=\"transaction::list|owner::sparse\"\n    which ideally will return a json response including `_links` and `_embeddded` objects inside the response containing either a map or array of transactions with links in the `_links` object and the desired projection in the `_embedded` object for both owner and transactions. \n    \n  \nThe service can choose to return just the accounts including links to transactions under the `_links` object as this is allowed by HAL. The Query Parameter can be used for evolving the service to match the desires of consumers - if many consumers are having the same wishes for what to embed - the owners of the service could start considering whether they want to include more in the responses and endure the added coupling between this service and the service that may deliver the embedded information. This coupling should of course not be synchronous.\n### Sensitive Id decomposition \nThe creation of an id can be challenging especially if the true semantic id is protected by law, which is the case for people. Therefore a either a UUID is suggested or a semi-semantic approach like firstName-middleName-sirName-dayInMonth-MonthInYear-Sequence, that allows for a human readable - yet not revealing id for a person.\nOther suggested methods for doing has been to create a hash(sensitive semantic key), which might work but will be vulnerable for a brute force reengineering effort. The response to that is often to salt it, that is salt(hash(sensitive sementic key)), and that is ok but is seems merely to be a very difficult way to create a UUID, which means we have a key that is developer unfriendly - at least compared to the more human readable key consisting of recognizable fragments from the real world.\nThe suggested approach is firstname-middlename-familyname-ddMM-sequencenumber\n#### Example:\n\n    hans-p-hansen-0112 the initial created Hans P Hansen born on the 1st of December\n    hans-p-hansen-0112-1 the second created Hans P Hansen born on the 1st of December\n    hans-p-hansen-0112-94 the 95th created Hans P Hansen born on the 1st of December\n \n    mike-hansson-0309 the initially created Mike Hansson born on the 3rd of September\n \n\n## Resilience\n\n### Limits\nThe server-side service might be busy for one or the other reason and need to tell the client that. In fact it is trying to say \"Be patient - I am rather busy right now\". Therefore the server returns a `503` error code (see response codes below) with a *Retry-After* header stating the time when it is expected that the server is no longer busy and can serve a consumer again.\nIf the server-side intercepts the consumer it may choose to return a 429 Too many Requests with a response stating that \"You are limited to XXXX requests per hour per `access_token` or `client_id` in total per  per `timeunit` overall. \n## Responses\nThe responses from calling resources in the API adheres to the specification of HTTP 1.1 and thus the status code, the headers used are found in that specification.\n### Status Codes\n#### Information on status code and headers are found under:\n\n      Status codes:\n      <https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>\n      \n      Headers:\n      <https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html>\n\n\nA couple of response codes will be described here as inspiration, but the most important thing is to work with the protocol and thus to read and understand what the status codes means and how they fit into the current situation in the API and write explicitly what the client can expect in every situation in order to make the API as developer friendly as possible. \n#### 200 OK\nThe 200 OK response signal everything went ok and there will usually be a response that contains a body corresponding to the initiating request's `Accept` header.\n#### 201 Created\nThe 201 Created follows after a successful `POST` or `PUT` and states where the newly resource was created in a `Location` header.\n#### 202 Accepted\nThe 202 Accepted response signals that the request was understood and the response will follow later, the response should state information can be obtained later concerning the request for the resource returning the 202. This is signalled in the `Location` header, to be nice the expectations of the client can be set using the `Retry_After` and issue a timeframe for when it makes sense to ask for a status again from the client.\n##### Headers\n``` Location: http://get/the/new/status/location\nRetry-After: 30 ```\n#### 301 Moved Permanently\nThe 301 is issued if a client asks for a resource that is no longer at the place it used to be. AS an example this could be a resource that has moved to a different part of the API. In that case a 301 is returned with a `Location` header containing the new position.\n##### Headers\n``` Location: http://this/is/the/new/location ```\n#### 400 Bad Request\nThe 400 response states that this request was wrong and should not be retried\n#### 401 Unauthorized\nThe 401 response states that this request did not have user authentication and that usually means that the client needs to either have a contract for that resource, authenticate the user, renew a token or ... in order to get access to the requested resource.\n\n#### 403 Forbidden\nThe 403 response states that this request have user authentication but does not have sufficient authorizations to access the resource.\n#### 404 Not Found\nThe 404 response states that the resource requested did not exist.\n#### 409 Conflict\nThe 409 response states that the attempted request for the resource is resulting in a form of conflict, which the client must resolve before retrying. This could be trying to POST changes to an object that would cause the object to be in an erroneous state.\n#### 503 Service Unavailable\nThe 503 response states that the server for some reason is unavailable.\n##### Headers\n``` Retry-After: Sat, 31 Dec 2016 23:59:59 GMT ```\nor\n``` Retry-After: 120 ```\n## Service terms\nThe terms of using the service is as follows, the contract found at <https://sample-bank.dk/services/contracts/2345678> states the general terms for using this service. Consumers can create their own individual contract and terms for usage at <https://sample-bank.dk/services/consumers>\n","termsOfService":"Sample-Bank internal only","contact":{"name":"Sample-Bank Application Architecture","url":"http://www.sample-bank.dk","email":"sample@sample-bank.dk"},"license":{"name":"(C) Sample-Bank 2016","url":"http://www.sample-bank.dk"}},"host":"banking.services.sample-bank.dk","securityDefinitions":{"oauth":{"type":"oauth2","flow":"implicit","authorizationUrl":"https://banking.services.sample-bank.dk/token.oauth2?grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=JWT","scopes":{"owners":"get access to own account","coOwners":"get access to co-owned accounts","poa":"get access on a owner's behalf"}},"key":{"type":"apiKey","in":"header","name":"access_token"},"Bearer":{"type":"apiKey","name":"Authorization","in":"header"}},"security":[{"oauth":["owners","coOwners","poa"]},{"key":[]}],"schemes":["https"],"basePath":"/","tags":[{"name":"select","description":"The resource supports selection of entries based on attribute values."},{"name":"sort","description":"The resource supports sorting of entries based on attribute values and direction."},{"name":"elements","description":"The resource supports paginations of entries based on page and page size."},{"name":"filter","description":"The resource supports filtering of returned json objects based on attribute values."},{"name":"embed","description":"The resource supports embedding of related json objects in the returned result based on relation and views/projections."},{"name":"interval","description":"The resource supports temporal selection of returned objects."},{"name":"immutable","description":"The ressource contains immutable instances and thus they can be cached for a very long period of time without loosing their relevance for the client."}],"paths":{"/accounts":{"get":{"summary":"Get an account listing","description":"Returns the accounts that the identified user has granted access to obtain.","security":[{"Bearer":[]}],"consumes":["application/json","application/json;v=1","application/json;concept=Account;v=1"],"produces":["application/json","application/json;v=1","application/json;concept=Account;v=1","application/json+account+1"],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Accounts"},"examples":{"application/hal+json;concept=Account;v=1":{"accounts":2,"total":2,"_links":{"self":{"href":"https://banking.services.sample-bank.dk/accounts","title":"All accessible accounts"},"accounts":[{"self":null,"href":"accounts/1234-567890","title":"Student Account"},{"self":null,"href":"accounts/1234-67891","title":"Nem Account"}]},"_embedded":{"accounts":[{"no":"1234-56789","capability":null,"name":"Student Account","owner":"Tom Hansen","balance":{"amount":1098,"currency":"DKK"},"lastActivity":"2016-10-12","_links":{"owner":{"href":"https://https://banking.services.sample-bank.dk/persons/tom-hansen-0304-32"},"transactions":{"name":"transactions","href":"https://banking.services.sample-bank.dk/accounts/1234-56789/transactions{?elements}","templated":true,"curies":[{"name":"oprs","href":"https://banking.services.sample-bank.dk/{rel}","templated":true}],"oprs:transfer-to-account":{"href":"accounts/1234-56789/transfer","templated":true},"oprs:payment":{"href":"payment-instructions/1234-56789/","templated":true}}}},{"no":"1234-67891","name":"Nem Konto","owner":"Viggo & Thelma Andersen Hansen WebShop","coOwner":"Mads Andersen Hansen","balance":{"amount":-1998905.32,"currency":"DKK"},"lastActivity":"2016-09-30","_links":{"owner":{"href":"https://https://banking.services.sample-bank.dk/persons/tom-andersen-hansen-0509-1"},"coOwner":{"href":"https://https://banking.services.sample-bank.dk/persons/mads-andersen-hansen-0112"},"transactions":{"href":"https://banking.services.sample-bank.dk/accounts/1234-67891/transactions{?elements}","templated":true}}}]}}}},"400":{"description":"Bad Request"},"404":{"description":"Not Found"},"500":{"description":"Service not available","schema":{"$ref":"#/definitions/Error"}},"503":{"description":"Service not available now - try later"}}}},"/accounts/{no}/transactions":{"get":{"tags":["sort","elements","interval","immutable"],"summary":"Get transactions for one account","consumes":["application/json"],"produces":["application/hal+json;v=1","application/hal+json;concept=Account;v=1","application/hal+json+account+1"],"parameters":[{"name":false,"type":"string","in":"path","description":"Account Id \\d{4}-\\d{5}","required":true},{"name":"select","type":"string","in":"query","description":"searching based on attributes in transaction","required":false},{"name":"sort","type":"string","in":"query","description":"sorting based on attributes in transaction","required":false},{"name":"interval","type":"string","in":"query","description":"limit result according to temporal aspects","required":false},{"name":"elements","type":"string","in":"query","description":"the starting page","required":false}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Transactions"},"examples":{"application/hal+json;concept=Transaction;v=1":{"_links":{"transactions":[{"self":{"href":"accounts/1234-567890/transactions/987654321","title":"Netto - Dankort ***7766"}},{"self":{"href":"accounts/1234-567890/transactions/987654322","title":"ElGiganten - Master kort ***4455"}},{"self":{"href":"accounts/1234-567890/transactions/987654323","title":"Small things Inc. - VISA kort ***6655"}}]},"_embedded":{"transactions":[{"time":"2016-08-26 11:01","activity":{"amount":23.45,"currency":"DKK"},"balance":2345.67,"interestDate":"2016-08-27","flag":true,"_links":{"self":{"href":"accounts/1234-567890/transactions/987654321","title":"Netto - Dankort ***7766"},"type":{"href":"expense-types/1001","title":"Dagligvarer"}}},{"time":"2016-08-25 22:12,","amount":{"amount":2345.67,"currency":"DKK"},"balance":10000.0,"interestDate":"2016-08-25","flag":true,"_links":{"self":{"href":"accounts/1234-567890/transactions/987654322","title":"ElGiganten - Master kort ***4455"},"type":{"href":"expense-types/1014","title":"Telefon, Computer, Internet og Tv"}}},{"time":"2016-08-25 03:03","amount":{"amount":-3.54,"currency":"USD"},"balance":"9976,66","interestDate":"2016-08-25","flag":true,"_links":{"self":{"href":"accounts/1234-567890/transactions/987654323","title":"Small things Inc. - VISA kort ***6655"},"type":{"href":"expense-types/1014","title":"Telefon, Computer, Internet og Tv"}}}]}}}},"400":{"description":"Bad Request"},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/Error"}}}}},"/accounts/{no}/reconciled-transactions/{txId}":{"put":{"summary":"Flag transaction entries for one account allowing the immutable nature of the transaction to be preserved and allowing the client to cache the immutable transactions really hard. This \"pattern\" makes it possible to consider immutable objects that needs some form of decoration to be unaffected by this decoration.","consumes":["application/json"],"produces":["application/hal+json;v=1","application/hal+json;concept=DecoratedTransaction;v=1","application/hal+json+decorated-transaction+1"],"parameters":[{"name":false,"in":"path","description":"Account Id \\d{4}-\\d{5}","required":true,"type":"string"},{"name":"txId","in":"path","description":"Transaction Id","required":true,"type":"string"},{"name":"reconcile","in":"body","description":"flag or unflag transaction and add a note to that particular transaction if desired","required":true,"schema":{"$ref":"#/definitions/DecoratedAccount"}}],"responses":{"200":{"description":"OK","schema":{"type":"string"}},"201":{"description":"Created"},"202":{"description":"Accepted"},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/Error"}}}}}},"definitions":{"Amount":{"type":"object","properties":{"amount":{"type":"number","format":"double"},"currency":{"type":"string","pattern":"\\w{3}"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Person":{"type":"object","properties":{"_links":{"type":"object","items":{"$ref":"#/definitions/HALLink"}},"sid":{"type":"string","pattern":"\\[a-z]+-[a-z]+-\\d{4}-*\\d*","description":"this is the non-sensitive semantic id for person"},"fullName":{"type":"string"},"cpr":{"type":"string","pattern":"\\d{10}","description":"do not use this in queries as this is sensitive information"}}},"Account":{"type":"object","properties":{"no":{"type":"string","pattern":"\\d{4}-\\d{5}","description":"the id for account and the natural non-sensitive semantic id"},"balance":{"description":"the current balance of and currency of the account - sadly this contextual comment will be ignored.This description is a warning in swagger, this is on purpose to illustrate a point.","$ref":"#/definitions/Amount"},"owner":{"description":"the owner of the account, which should be included as a link and thus avoid heavy coupling to the person service for updates on anything else than the semantical id and thus the link. It would be useful to be able to include the projection of Person to embed - if the Account Service will endure the coupling for embedding persons such as the owner at a more sophisticated level than just the link. Therefore support for embedding of particular types and projections in Swagger would be nice. This description is a warning in swagger, this is on purpose to illustrate a point.","$ref":"#/definitions/Person"},"coOwner":{"description":"the co-owner of the account, which should be included as a link and thus avoid heavy coupling to the person service for updates on anything else than the semantical id and thus the link. It would be useful to be able to include the projection of Person to embed - if the Account Service will endure the coupling for embedding persons such as the owner at a more sophisticated level than just the link. Therefore support for embedding of particular types and projections in Swagger would be nice. This description is a warning in swagger, this is on purpose to illustrate a point.","$ref":"#/definitions/Person"},"_links":{"type":"object","items":{"$ref":"#/definitions/HALLink"}},"_embedded":{"type":"object","items":{"$ref":"#/definitions/MixOfDifferentObjects"}}}},"Transactions":{"type":"object","properties":{"transactions":{"type":"integer","description":"the number of transactions in response"},"total":{"type":"integer","description":"the total number of transactions on an account"},"_links":{"type":"object","items":{"$ref":"#/definitions/HALLink"}},"_embedded":{"type":"object","items":{"$ref":"#/definitions/Transaction"}}}},"Transaction":{"type":"object","properties":{"_links":{"type":"object","items":{"$ref":"#/definitions/HALLink"}},"amount":{"description":"the amount and currency of the transaction registered - sadly this contextual comment will be ignored. This description is a warning in swagger, this is on purpose to illustrate a point concerning context support.","$ref":"#/definitions/Amount"},"balance":{"description":"the current balance of the account after the transaction was registered - sadly this contextual comment will be ignored.This description is a warning in swagger, this is on purpose to illustrate a point concerning context support.","$ref":"#/definitions/Amount"},"description":{"type":"string","description":"the description of a transaction given by the service"},"date":{"type":"string","format":"date","description":"the time for the transaction to be recorded by the service"}}},"DecoratedAccount":{"type":"object","description":"a way to decorate immutable objects such as transactions and thus let them be cachable for a long time, whereas this is more volatile and thus cannot be cached at the same level. This is to separate concepts.","properties":{"_links":{"$ref":"#/definitions/Transaction"},"reconciled":{"type":"boolean","description":"the user can signal whether the transaction was reconciled or not"},"note":{"type":"string","description":"the user can write a note on the transaction to know that"},"category":{"type":"string","description":"the sort of category"}}},"Accounts":{"type":"object","properties":{"accounts":{"type":"integer","description":"the number of accounts in response"},"total":{"type":"integer","description":"the number of accounts in all"},"_links":{"type":"object","items":{"$ref":"#/definitions/HALLink"}},"_embedded":{"type":"object","items":{"$ref":"#/definitions/Account"}}}},"HALLink":{"type":"object","description":"the HAL link is specified in the specification chapter 5","properties":{"href":{"type":"string","description":"the full reference to a related resource"},"name":{"type":"string","description":"a reference to a related resource as secondary identifier"},"title":{"type":"string","description":"a human readable reference to a related resource"},"type":{"type":"string","description":"the specific content-type including version and concept"}}},"MixOfDifferentObjects":{"type":"object","description":"a way for specifying how objects of different types are linked and especially embedded into Swagger is needed in order to be able to deliver a precise API description of what an API actually offers to the clients."}}}