Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I have a REST service I want to document for my client developing team.
So I added some Links from Spring-Hateoas to my resources API, and plugged into it swagger-springmvc #Api... annotations to document everything and make a good API reference for my Angular team to be able to understand my REST service.
The problem is that swagger is unable to discover what links are possible, and just give me a big array of Links without saying their possible values.
Here is a (simple) example. Swagger detects :
Model Schema
CollectionListResource {
collections (array[CollectionResource]): All available collections,
links (array[Link]): Relations for next actions
}
CollectionResource {
collectionId (string): Collection Unique Id,
name (string): Human readable collection name,
links (array[Link]): Relations for next actions
}
Link {
rel (string, optional),
templated (boolean, optional),
href (string, optional)
}
And I get in fact in HAL :
{"collections":
[{"collectionId":"5370a206b399c65f05a7c59e",
"name":"default",
"_links":{ [
"self":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
},
"delete":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
}
]}
}, ...]}
I've tried to extend Link and ResourceSupport to have annoted version of them but this lead me to nowhere.
Is there a way/tool I could use to generate a good API doc telling that a self relation is to get the content, and a delete relation is to delete the collection ?
I liked swagger for its good UI, but I don't mind changing my documentation tool if its help having the doc really complete.
I could eventually think of changing spring-hateoas for another link generator, but I'm not sure there is a better tool available right now.
Swagger-UI as such is not hypermedia aware; or atleast its limited in that it can ONLY navigate from top level apis to api listings. That has not changed much in v2.0 of the spec either, with the notable addition of linking to external documents for out of band documentation.
What you need is a hybrid of the HAL browser and the swagger-ui. As you rightly pointed out, there is a semantic gap between the word "delete" and what it means in the context of a collection resource. HAL uses a combination of curies and optionally a profile document ALPS to bridge this gap. Curies are nothing but namespaced versions of linked relations so that they dont collide with other domains. Restful Web APIs is a great resource to learn more about these ideas and how to design media types. The spring data rest project also has a great example of how to achieve that.
One of the ways that I think would work is to adjust swagger specification to support an operations oriented view rather than api listing oriented view, not really possible in the the timeframe that you're possibly working with.
Use existing RFC's like rfc5023 to have a shared understanding of what "edit"ing a resource means.
Lastly if none of the standard link relationships express the intent of the action, define your own application specific semantics that provide documentation for these application specific link relationships. That way clients of your service will have a shared understanding of these relations within the context of your application.
Below is an example that demonstrates and combines these approaches.
{"collections":
[{"collectionId":"5370a206b399c65f05a7c59e",
"name":"default",
"curies": [
{
"name": "sw",
"href": "http://swagger.io/rels/{rel}",
"templated": true
},
{
"name": "iana",
"href": "https://www.rfc-editor.org/rfc/rfc5023",
"templated": false
},
{
"name": "col",
"href": "http://localhost:9080/collections/{rel}",
"templated": false
}
],
"_links":{ [
"self":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
},
"sw:operation":{
"href":"http://localhost:9080/api-docs/collections#delete"
},
"sw:operation":{
"href":"http://localhost:9080/api-docs/collections#search"
},
"sw:operation":{
"href":"http://localhost:9080/api-docs/collections#update"
},
"iana:edit":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
},
"col:delete": {
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
}
]}
}, ...]}
So from most generic to most specific, the solution (in that order) is
The iana qualified links have a specific meaning, in this case the "edit" has a very specific meaning that every restful client can implement. This is a generialized link type.
The sw qualified link relations have a special meaning as well, it implies the href deep links to operations in the swagger api documentation.
The col qualified links are application specific links that only your application knows about.
I know this doesn't answer your question precisely, and the tools in this space are still evolving. Hope this helps.
DISCLAIMER: I'm one of the core maintainers of springfox which is a spring integration solution that makes it easy to provide swagger service descriptions. So any feedback on how you'd like it to solve this problem is very welcome!
Related
I was wondering if an object type that has an id property has to have the same content given the same id. At the moment the same id can have different content.
The following query:
const query = gql`
query products(
$priceSelector: PriceSelectorInput!
) {
productProjectionSearch(
priceSelector: $priceSelector
) {
total
results {
masterVariant {
# If you do the following it will work
# anythingButId: id
id
scopedPrice {
country
}
}
}
}
}
`;
If the PriceSelectorInput is {currency: "USD", country: "US"} then the result is:
{
"productProjectionSearch": {
"total": 2702,
"results": [
{
"name": "Sweater Pinko white",
"masterVariant": {
"id": 1,
"scopedPrice": {
"country": "US",
"__typename": "ScopedPrice"
},
"__typename": "ProductSearchVariant"
},
"__typename": "ProductProjection"
}
],
"__typename": "ProductProjectionSearchResult"
}
}
If the PriceSelectorInput is {currency: "EUR", country: "DE"} then the result is:
{
"productProjectionSearch": {
"total": 2702,
"results": [
{
"name": "Sweater Pinko white",
"masterVariant": {
"id": 1,
"scopedPrice": {
"country": "DE",
"__typename": "ScopedPrice"
},
"__typename": "ProductSearchVariant"
},
"__typename": "ProductProjection"
}
],
"__typename": "ProductProjectionSearchResult"
}
}
My question is that masterVariant of type ProductSearchVariant has id of 1 in both cases but different values for scopedPrice. This breaks apollo cache defaultDataIdFromObject function as demonstrated in this repo. My question is; is this a bug in apollo or would this be a violation of a graphql standard in the type definition of ProductSearchVariant?
TLDR
No it does not break the spec. The spec forces absolutely nothing in regards caching.
Literature for people that may be interested
From the end of the overview section
Because of these principles [... one] can quickly become productive without reading extensive documentation and with little or no formal training. To enable that experience, there must be those that build those servers and tools.
The following formal specification serves as a reference for those builders. It describes the language and its grammar, the type system and the introspection system used to query it, and the execution and validation engines with the algorithms to power them. The goal of this specification is to provide a foundation and framework for an ecosystem of GraphQL tools, client libraries, and server implementations -- spanning both organizations and platforms -- that has yet to be built. We look forward to working with the community in order to do that.
As we just saw the spec says nothing about caching or implementation details, that's left out to the community. The rest of the paper proceeds to give details on how the type-system, the language, requests and responses should be handled.
Also note that the document does not mention which underlying protocol is being used (although commonly it's HTTP). You could effectively run GraphQL communication over a USB device or over infra-red light.
We hosted an interesting talk at our tech conferences which you might find interesting. Here's a link:
GraphQL Anywhere - Our Journey With GraphQL Mesh & Schema Stitching • Uri Goldshtein • GOTO 2021
If we "Ctrl+F" ourselves to look for things as "Cache" or "ID" we can find the following section which I think would help get to a conclusion here:
ID
The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, it is not intended to be human‐readable. While it is often numeric, it should always serialize as a String.
Result Coercion
GraphQL is agnostic to ID format, and serializes to string to ensure consistency across many formats ID could represent, from small auto‐increment numbers, to large 128‐bit random numbers, to base64 encoded values, or string values of a format like GUID.
GraphQL servers should coerce as appropriate given the ID formats they expect. When coercion is not possible they must raise a field error.
Input Coercion
When expected as an input type, any string (such as "4") or integer (such as 4) input value should be coerced to ID as appropriate for the ID formats a given GraphQL server expects. Any other input value, including float input values (such as 4.0), must raise a query error indicating an incorrect type.
It mentions that such field it is commonly used as a cache key (and that's the default cache key for the Apollo collection of GraphQL implementations) but it doesn't tell us anything about "consistency of the returned data".
Here's the link for the full specification document for GraphQL
Warning! Opinionated - My take on ID's
Of course all I am about to say has nothing to do with the GraphQL specification
Sometimes an ID is not enough of a piece of information to decide whether to cache something. Let's think about user searches:
If I have a FavouriteSearch entity that has an ID on my database and a field called textSearch. I'd commonly like to expose a property results: [Result!]! on my GraphQL specification referencing all the results that this specific text search yielded.
These results are very likely to be different from the moment I make the search or five minutes later when I revisit my favourite search. (Thinking about a text-search on a platform such as TikTok where users may massively upload content).
So based on this definition of the entity FavouriteSearch it makes sense that the caching behavior is rather unexpected.
If we think of the problem from a different angle we might want a SearchResults entity which could have an ID and a timestamp and have a join-table where we reference all those posts that were related to the initial text-search and in that case it would make sense to return a consistent content for the property results on our GraphQL schema.
Thing is that it depends on how we define our entities and it's ultimately not related to the GraphQL spec
A solution for your problem
You can specify how Apollo generates the key for later use as key on the cache as #Matt already pointed in the comments. You may want to tap into that and override that behavior for those entitites that have a __type equal to your masterVariant property type and return NO_KEY for all of them (or similar) in order to avoid caching from your ApolloClient on those specific fields.
I hope this was helpful!
I have a use-case where the "href" of the forms in the Thing Description must contain the MAC address of the device (or some ID unique to that device). The form description would look as follows:
"forms": [
{
"op": [
"readproperty"
],
"href": "/things/01-02-03-04-05-06/properties/temperature",
"contentType": "application/json",
"mqv:controlPacketValue": "SUBSCRIBE"
}
]
I think it would make sense to use a placeholder for the MAC address like this
"href": "/things/[MAC]/properties/temperature"
The device would then replace the placeholder with its own MAC. This way, the Thing Description doesn't have to be adjusted when a different device is used.
Does the WoT specification consider the use of such placeholders in the Thing Description? Does anything speak against the Thing modifying its own Thing Description?
This idea might also be expanded to having the Thing setting other attributes in the TD, to the Thing completely generating its own TD (although the effort for this stand in no relation to the use, in my case).
Version 1.1 of the TD specification defines Thing Models (https://w3c.github.io/wot-thing-description/#thing-model) where such placeholders can be used. However, Thing Models are not exchanged with usual WoT Consumers since they would expect no out-of-band information other than security credentials. You can however think of a mechanism that sends a Thing Model and a placeholder map that can be used to generate a TD with concrete endpoints.
Regarding how a TD can be managed, especially updated, it is a bit tricky. You need to think that there are WoT Consumers that consume a TD and do not have a way of handling changes, i.e. being notified of updates and how to incorporate those updates into the Consumer application logic. You can also look at https://github.com/w3c/wot-thing-description/issues/1174 . The Discovery specification has started working on how TDs are managed though, you can look at https://w3c.github.io/wot-discovery/
This top-ranking Stackoverflow answer from 10 years ago suggests using POST /users/:user_id/reset_password to initiate a password reset.
I know the API platform recommends against using custom operations. The docs page for the Symfony Messenger integration uses a ResetPasswordRequest entity (with a username field). That makes sense to me.
Say I have a User and Notification entity and maybe a joined UserNotification (with a hasRead) entity as well. I want to expose an endpoint on my API to mark all the notifications older than a month as read. So I might make a ClearOldNotification entity, again with a username field.
Another example might be I want a report showing Customers that haven't been contacted due to some criteria. So I want to join the tables in the server and return a custom JSON data object. Again I could make a CustomerNoContact entity.
The issue I see is that I now have a distinction between pure entities, like a User or Product, as opposed to these service type entities.
Is this method of making individual entities classes for actions the recommended, best practice for Symfony and API Platform?
Should I be name-spacing (or something) these entities differently within my app to distinguish them?
I could imagine on a really large and complex application you could have hundreds of these service entities, compared to the pure entities. Is that expected or desired?
Can anyone recommend some good resources on this pattern?
You're asking for a best practice for two different use cases. Let's break it down:
ClearOldNotification
I think you've already found the solution: using Messenger. As you've read, there is an example in the documentation for this use case:
#[ApiResource(collectionOperations: [
"post", "get", "delete",
"reset_password" => ["status" => 202, "messenger" => "input", "input" => ResetPasswordRequest::class, "output" => false, "method" => "POST", "path" => "/users/reset_password"]
]
)]
final class User
{
}
The ResetPasswordRequest class is a Data Transfer Object (DTO). In your ResetPasswordRequestHandler you should inject the service that is responsible for resetting the password and sending an email.
CustomerNoContact
This could be a Custom (Doctrine ORM) Filter.
I'm currently working on a project in which we perform "Nearby" queries for places using keywords, and then we make follow-up "Detail" requests to obtain more information about specific places of interest.
With Google's new pricing model in the works, the documentation warns about the cost of the Nearby search, but the warning seems to imply that the follow-up detail request will no longer be necessary because our original search should give us everything we need:
By default, when a user selects a place, Nearby Search returns all of
the available data fields for the selected place, and you will be
billed accordingly. There is no way to constrain Nearby Search
requests to only return specific fields. To keep from requesting (and
paying for) data that you don't need, use a Find Place request
instead.
However, I'm not seeing this. When I run a sample request, the results from my Nearby request contains only minimal data related to the places Google finds. To get details, I still have to do a follow-up detail request.
Does anyone know if there's something I may be overlooking? I'm including my request URL (sans API key).
https://maps.googleapis.com/maps/api/place/nearbysearch/json?key=xxxxxxxxxx&location=30.7329,-88.081987&radius=5000&keyword=insurance
And this is an example of one of the results I received:
{
"geometry": {
"location": {
"lat": 30.69254,
"lng": -88.0443999
},
"viewport": {
"northeast": {
"lat": 30.69387672989272,
"lng": -88.04309162010728
},
"southwest": {
"lat": 30.69117707010728,
"lng": -88.04579127989273
}
}
},
"icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
"id": "53744cdc03f8a9726593a767424b14f7f8f86049",
"name": "Ann M Hartwell - Aflac Insurance Agent",
"place_id": "ChIJj29KxNZPmogRJovoXjMDpQI",
"plus_code": {
"compound_code": "MXV4+26 Mobile, Alabama",
"global_code": "862HMXV4+26"
},
"reference": "CmRbAAAAcHM1P7KgNiZgVOm1pWojLto9Bqx96h2BkA-IyfN5oAz1-OICsRXiZOgwmwHb-eX7z679eFjpzPzey0brgect1UMsAiyawKpb5NLlgr_Pk8wBJpagRcKQF1VSvEm7Nq6CEhCfR0pM5wiiwpqAE1eE6eCRGhQPJfQWcWllOVQ5e1yVpZYbCsD01w",
"scope": "GOOGLE",
"types": [
"insurance_agency",
"point_of_interest",
"establishment"
],
"vicinity": "70 N Joachim St, Mobile"
}
I thought about deleting this question, but I guess I'll leave it up in case anyone else is confused like I was.
It turns out the extra detail fields I was looking for in the Nearby Search results were there...sort of.
Google's new pricing model categorizes place data fields into three tiers: Basic, Contact, and Atmosphere (Basic data is free, but the other two add to the cost).
As part of these changes, Place API calls have been expanded to allow users to specify the data fields they want so that they don't have to pay for that extra data if they don't need it.
The Nearby Search query, as per the note in the question, includes all the data fields available, and doesn't support a parameter for controlling the data -- it's always going return data that falls into the [Basic + Contact + Atmosphere] bucket.
So far, that's all well and good.
Where things became confusing to me, though, is the specifics of what is included in the different data tiers. I skimmed through these notes several times before I noticed the contents were different.
This is how the fields break down with the Places details request:
Basic
The Basic category includes the following fields: address_component,
adr_address, alt_id, formatted_address, geometry, icon, id, name,
permanently_closed, photo, place_id, plus_code, scope, type, url,
utc_offset, vicinity
Contact
The Contact category includes the following fields:
formatted_phone_number, international_phone_number, opening_hours,
website
Atmosphere
The Atmosphere category includes the following fields: price_level,
rating, review
And this is how it looks for the Places search request:
Basic
The Basic category includes the following fields: formatted_address,
geometry, icon, id, name, permanently_closed, photos, place_id,
plus_code, scope, types
Contact
The Contact category includes the following field: opening_hours
(Place Search returns only open_now; use a Place Details request to
get the full opening_hours results). Atmosphere
The Atmosphere category includes the following fields: price_level,
rating
I haven't found documentation for it, specifically, but the results from a Nearby Search request seems close (but not identical) to the Place search (including Contact and Atmosphere).
I had originally thought the fact that Nearby Search results now include Contact and Atmosphere data (when available), that meant it would contain all the fields itemized as Contact and Atmosphere data in the Place details documentation, but that's not the case.
As per below link create interest functionality is nto avaialable.
http://developer.mailchimp.com/documentation/mailchimp/reference/lists/interest-categories/interests/#
But using API playgroung you can create interest. Even tried with REST api and I am able to create interest. Please let me know if "create interest " API has been removed from above page.
I think it never wasn't on that page. This new API Documentation lacks many things that are possible.
If you want to create new interest you can just POST to this endpoint:
/lists/{list_id}/interest-categories/{interest_category_id}/interests
Example request body:
{
"list_id": "id_of_the_list",
"name": "name of the interest",
"display_order": 1
}
So the answer for your question is that I am pretty sure they just haven't created documentation for that one yet.