Creating snippet for shared model - spring-restdocs

Is it possible to generate snippet for a nested bean shared between different response structures ?
Address model
class Address {
String state;
Integer postcode;
}
Response from endpoint 1 (R1)
{
"status": 1,
"address": {
"state": "abc",
"postcode": 3
}
}
Response from endpoint 2 (R2)
{
"id": 2,
"currentAddress": {
"state": "abc",
"postcode": 2
}
}
I would like to generate the snippet for Address model once and reuse it in generated snippets for R1 and R2.

As described in the reference documentation, you can use subsectionWithPath("address") and subsectionWithPath("currentAddress") to document the address subsection in R1 and R2 and then cross-link to a separate section in your documentation that describes the address structure in detail. The REST Docs samples show an example of this cross-linking.
To describe the address structure in detail, you can use a combination of responseFields and beneathPath to generate a snippet for a specific part of a response.

Related

Strapi API Rest V 3.6.8 how to search posts by title?

I have installed version 3.6.8 of Strapi
In the docs for v3.x
https://strapi.gitee.io/documentation/v3.x/content-api/parameters.html#filter
Filters are used as a suffix of a field name:
No suffix or eq: Equals
ne: Not equals
lt: Less than
gt: Greater than
lte: Less than or equal to
gte: Greater than or equal to
in: Included in an array of values
nin: Isn't included in an array of values
contains: Contains
ncontains: Doesn't contain
containss: Contains case sensitive
ncontainss: Doesn't contain case sensitive
null: Is null/Is not null
And I can see those examples
GET /restaurants?_where[price_gte]=3
GET /restaurants?id_in=3&id_in=6&id_in=8
etc..
So I tried
/posts?_where[title_contains]=foo
/posts?title_contains=foo
And I also tried the "new way" in V4
/posts?filters[title][contains]=foo
But all of this attempts return all the post, exactly the same than just doing
/posts?
Any idea how to filter by post title and/or post body?
Almost there my friend! The issue you are facing called deep filtering (please follow the link for documentation).
In Short: the title field is located inside the attributes object for each item
Your items may look something similar to this:
{
"data": [
{
"id": 1,
"attributes": {
"title": "Restaurant A",
"description": "Restaurant A's description"
},
"meta": {
"availableLocales": []
}
},
{
"id": 2,
"attributes": {
"title": "Restaurant B",
"description": "Restaurant B's description"
},
"meta": {
"availableLocales": []
}
},
]
}
And therefor the filter should be
/api/posts?filters[attributes][title][$contains]=Restaurant
Also note:
the $ sign that should be included for your operator (in our case contains)
the api prefix you should use before the plural api id (e.g. posts, users, etc.)
you may prefer using $containsi operator in order to ignore upper and lower case letters (better for searching operations)
Let me know if it worked for you!

Magento 2.4 API, POST product custom_attributes

I need to add/update products using the REST API. I cannot figure how to add a custom_attributes, knowing only the value/label of the attribute and not the ID (attribute of type 'dropdown' or 'selectable')
POST /rest/all/V1/products
{
"product": {
"sku": "D119",
"custom_attributes": [{
"attribute_code": "year",
"value": "2015"
}]
}
}
Upper code works fine if I just put in the ID in the value field. But a sourcing system wouldnt know the id's....
Side note: The M2 backend import function is capable of importing value/label of the attribute? How come?

Magento 2 REST API Customer Custom Attribute

The Magento 2 REST API Documentation explains a way to set custom_attributes on a customer when updating or creating it. http://devdocs.magento.com/swagger/index_20.html#/
Unfortunately I couldn't get this to work...
My POST and PUT JSON request data is :
{
"customer": {
"custom_attributes": [
{
"attribute_code": "firstname",
"value": "TEST"
}
],
"email": "someone#exaxmple.com",
"extension_attributes": [],
"firstname": "Someone",
"gender": null,
"lastname": "Else",
"middlename": null,
"taxvat": null,
"website_id": "1"
}
}
The Customer is created but the Firstname is not "TEST".
Is there anyone who had the same problem and fixed it? Please let me know how.
My best guess is that, since Firstname is an existing Out-Of-The-Box attribute - the OOTB attribute name-value mapping assignment will take precedence.
Could you try again, with a unique custom attribute name (i.e. something that doesn't clash with OOTB attribute names)
You will need to DEFINE a custom-customer-attribute before you can use the M2 API to perform operations on that custom-customer-attribute.
This StackExchange thread - https://magento.stackexchange.com/questions/88245/magento2-create-a-customer-custom-attribute - has additional information on how to go about setting up a custom-customer-attribute.

Return an array with a single element using Gson and HAL (Hypertext Application Language)

I'm having problems using Halarious (Java library for the HAL specification) and Gson to serialise a list of links in the _links section with just a single element. The array is serialized into an object instead of being an array with a single link.
EXAMPLE:
What I'm getting now is:
{
"year": 2008,
"_embedded": {
"items": {
"_links": {
"self": {
"href": "/first_item"
}
}
}
}
}
Instead of:
{
"year": 2008,
"_embedded": {
"items": {
"_links": {
"self": [
{
"href": "/first_item"
}
]
}
}
}
}
I solved the same problem with the _embedded section but I can't solve it for the links section.
Thanks
I solved using a workaround. I dont' use #HalLink but a surrogate ad hoc class that contains all the hierarchy and which instance is named "_links".
So using a list of custom Href objects when it has a single link I'll receive back the expected self attribute as list with a single element.
After all the HAL documentation (http://stateless.co/hal_specification.html) says: ​"If you're unsure whether the link should be singular, assume it will be multiple" and from http://blog.stateless.co/post/13296666138/json-linking-with-hal "Where a relation may potentially have multiple links sharing the same key the value should be an array of link objects".
​In this way I won't break consumers having them to deal with either a JSON array or an object.

Pagination response payload from a RESTful API

I want to support pagination in my RESTful API.
My API method should return a JSON list of product via /products/index. However, there are potentially thousands of products, and I want to page through them, so my request should look something like this:
/products/index?page_number=5&page_size=20
But what does my JSON response need to look like? Would API consumers typically expect pagination meta data in the response? Or is only an array of products necessary? Why?
It looks like Twitter's API includes meta data: https://dev.twitter.com/docs/api/1/get/lists/members (see Example Request).
With meta data:
{
"page_number": 5,
"page_size": 20,
"total_record_count": 521,
"records": [
{
"id": 1,
"name": "Widget #1"
},
{
"id": 2,
"name": "Widget #2"
},
{
"id": 3,
"name": "Widget #3"
}
]
}
Just an array of products (no meta data):
[
{
"id": 1,
"name": "Widget #1"
},
{
"id": 2,
"name": "Widget #2"
},
{
"id": 3,
"name": "Widget #3"
}
]
ReSTful APIs are consumed primarily by other systems, which is why I put paging data in the response headers. However, some API consumers may not have direct access to the response headers, or may be building a UX over your API, so providing a way to retrieve (on demand) the metadata in the JSON response is a plus.
I believe your implementation should include machine-readable metadata as a default, and human-readable metadata when requested. The human-readable metadata could be returned with every request if you like or, preferably, on-demand via a query parameter, such as include=metadata or include_metadata=true.
In your particular scenario, I would include the URI for each product with the record. This makes it easy for the API consumer to create links to the individual products. I would also set some reasonable expectations as per the limits of my paging requests. Implementing and documenting default settings for page size is an acceptable practice. For example, GitHub's API sets the default page size to 30 records with a maximum of 100, plus sets a rate limit on the number of times you can query the API. If your API has a default page size, then the query string can just specify the page index.
In the human-readable scenario, when navigating to /products?page=5&per_page=20&include=metadata, the response could be:
{
"_metadata":
{
"page": 5,
"per_page": 20,
"page_count": 20,
"total_count": 521,
"Links": [
{"self": "/products?page=5&per_page=20"},
{"first": "/products?page=0&per_page=20"},
{"previous": "/products?page=4&per_page=20"},
{"next": "/products?page=6&per_page=20"},
{"last": "/products?page=26&per_page=20"},
]
},
"records": [
{
"id": 1,
"name": "Widget #1",
"uri": "/products/1"
},
{
"id": 2,
"name": "Widget #2",
"uri": "/products/2"
},
{
"id": 3,
"name": "Widget #3",
"uri": "/products/3"
}
]
}
For machine-readable metadata, I would add Link headers to the response:
Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last
(the Link header value should be urlencoded)
...and possibly a custom total-count response header, if you so choose:
total-count: 521
The other paging data revealed in the human-centric metadata might be superfluous for machine-centric metadata, as the link headers let me know which page I am on and the number per page, and I can quickly retrieve the number of records in the array. Therefore, I would probably only create a header for the total count. You can always change your mind later and add more metadata.
As an aside, you may notice I removed /index from your URI. A generally accepted convention is to have your ReST endpoint expose collections. Having /index at the end muddies that up slightly.
These are just a few things I like to have when consuming/creating an API.
I would recommend adding headers for the same. Moving metadata to headers helps in getting rid of envelops like result , data or records and response body only contains the data we need. You can use Link header if you generate pagination links too.
HTTP/1.1 200
Pagination-Count: 100
Pagination-Page: 5
Pagination-Limit: 20
Content-Type: application/json
[
{
"id": 10,
"name": "shirt",
"color": "red",
"price": "$23"
},
{
"id": 11,
"name": "shirt",
"color": "blue",
"price": "$25"
}
]
For details refer to:
https://github.com/adnan-kamili/rest-api-response-format
For swagger file:
https://github.com/adnan-kamili/swagger-response-template
As someone who has written several libraries for consuming REST services, let me give you the client perspective on why I think wrapping the result in metadata is the way to go:
Without the total count, how can the client know that it has not yet received everything there is and should continue paging through the result set? In a UI that didn't perform look ahead to the next page, in the worst case this might be represented as a Next/More link that didn't actually fetch any more data.
Including metadata in the response allows the client to track less state. Now I don't have to match up my REST request with the response, as the response contains the metadata necessary to reconstruct the request state (in this case the cursor into the dataset).
If the state is part of the response, I can perform multiple requests into the same dataset simultaneously, and I can handle the requests in any order they happen to arrive in which is not necessarily the order I made the requests in.
And a suggestion: Like the Twitter API, you should replace the page_number with a straight index/cursor. The reason is, the API allows the client to set the page size per-request. Is the returned page_number the number of pages the client has requested so far, or the number of the page given the last used page_size (almost certainly the later, but why not avoid such ambiguity altogether)?
just add in your backend API new property's into response body.
from example .net core:
[Authorize]
[HttpGet]
public async Task<IActionResult> GetUsers([FromQuery]UserParams userParams)
{
var users = await _repo.GetUsers(userParams);
var usersToReturn = _mapper.Map<IEnumerable<UserForListDto>>(users);
// create new object and add into it total count param etc
var UsersListResult = new
{
usersToReturn,
currentPage = users.CurrentPage,
pageSize = users.PageSize,
totalCount = users.TotalCount,
totalPages = users.TotalPages
};
return Ok(UsersListResult);
}
In body response it look like this
{
"usersToReturn": [
{
"userId": 1,
"username": "nancycaldwell#conjurica.com",
"firstName": "Joann",
"lastName": "Wilson",
"city": "Armstrong",
"phoneNumber": "+1 (893) 515-2172"
},
{
"userId": 2,
"username": "zelmasheppard#conjurica.com",
"firstName": "Booth",
"lastName": "Drake",
"city": "Franks",
"phoneNumber": "+1 (800) 493-2168"
}
],
// metadata to pars in client side
"currentPage": 1,
"pageSize": 2,
"totalCount": 87,
"totalPages": 44
}
This is an interessting question and may be perceived with different arguments. As per the general standard meta related data should be communicated in the response headers e.g. MIME type and HTTP codes. However, the tendency I seem to have observed is that information related to counts and pagination typically are communicated at the top of the response body. Just to provide an example of this The New York Times REST API communicate the count at the top of the response body (https://developer.nytimes.com/apis).
The question for me is wheter or not to comply with the general norms or adopt and do a response message construction that "fits the purpose" so to speak. You can argue for both and providers do this differently, so I believe it comes down to what makes sense in your particular context.
As a general recommendation ALL meta data should be communicated in the headers. For the same reason I have upvoted the suggested answer from #adnan kamili.
However, it is not "wrong" to included some sort of meta related information such as counts or pagination in the body.
generally, I make by simple way, whatever, I create a restAPI endpoint for example "localhost/api/method/:lastIdObtained/:countDateToReturn"
with theses parameters, you can do it a simple request.
in the service, eg. .net
jsonData function(lastIdObtained,countDatetoReturn){
'... write your code as you wish..'
and into select query make a filter
select top countDatetoreturn tt.id,tt.desc
from tbANyThing tt
where id > lastIdObtained
order by id
}
In Ionic, when I scroll from bottom to top, I pass the zero value, when I get the answer, I set the value of the last id obtained, and when I slide from top to bottom, I pass the last registration id I got