I would like to use GraphiQL docs to document my GraphQL API. The out-of-the-box version already looks pretty useful, however I would like to enrich it by the information about permissions.
My imagination is that in this
there will be another section, i.e. "Permissions", with some description of the permissions.
My question: is this the way to do it? If not, how can one express permissions in the GraphiQL Docs? And if this could be the way, is there any tool capable of doing this?
What's shown in GraphiQL (or similar tools like GraphQL Playground, Altair, etc.) is limited to what can be returned through introspection of the schema, which is limited by what the spec specifies. You can add descriptions to types, fields, arguments, enum values and directives. A description for the schema itself is in the works.
At best, you could add a description to your field specifying the permissions. You can use markdown if you want to jazz it up.
Related
I wonder how to make some fields of an entity extension searchable in the administration through the "/api/search/my-entity" api-endpoint. By default they are not considered during search as it looks like.
I found the answer by debugging the search-endpoint:
The association-Field of the EntityExtension needs to have a SearchRanking-flag:
...->addFlags(new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING))
Then you can add SearchRanking-flags in the EntityExtensionDefinition as you like, e.g.:
(new StringField('test', 'test'))->addFlags(new SearchRanking(SearchRanking::HIGH_SEARCH_RANKING)),
After that the fields are searchable via the search-endpoint :)
As far as the API is concerned, search functionality should automatically be generated following your custom entity definitions.
When it comes to facilitate Admin search for your entity, you need to add some code to the administration component as described in the docs: https://developer.shopware.com/docs/guides/plugins/plugins/administration/search-custom-data (even though it looks not fully up-to-date w.r.t to the current Shopware versions).
I have an API in Postman that has defined JSON schemas for every request\response.
I also have a collection of tests that i use for testing this API.
But I don't know how to connect these two substances(things)
I have been searching for a solution for quite a while now and havent found an example set-up or a tutorial how? instead of creating a variable with actual schema in my test collection, I want to reuse already existing schema from API by $ref or some other link method.
This is my first question here, writing it just cause i haven't found a proper answer but functionality that i seek sounds really basic and logical.
Update from Valentin Despa:
"Please note that the API definition is written in a specification like Open API (or similar). It is not the same as the JSON schema which refers to the response body only."
So we can't validate response using that schema.
Is it possible to show that some collections can be accessed only by user which has same permissions/roles?
For example how it is in https://api.slack.com/methods/channels.create
Expected scopes:
channels:write read
The concept of access permissions exists at the layer of business
logic and is not intrinsic to GraphQL itself. I think your best bet
here may be documenting any constraints that in description fields in
the schema, where they will then be shown in the GraphiQL
documentation explorer.
https://github.com/graphql/graphiql/issues/564
I have been working with spring-data-rest and repositories. Since RESTful apis are supposed to be self-describing, how would you find out the properties of an resource? Is this possible w/o an API document or some special coding?
Person/People example... if there were no people in the repository how could I find out what one looks like? Perhaps there is a url that asks the service to describe the properties of a Person, but I haven't been able to find it.
A service can deliver a resource in one or more media types. A client has to understand the media type beforehand. If the media type was jpeg you wouldn't expect the service to deliver a description of the jpeg file format and compression algorithm, would you? It's just the same with a person media type. A person may even be represented with more than one media type. How would a description of a binary format look like?
The APIs should be discoverable, yes, but what a resource looks like is implied by a media type and must be known to a client.
Of course, you could always create a service, that returns some kind of description, but that's not part of REST.
Having said that, depending on the media type there are some standards for descriptions. XML even is kind of based on such standards. It offers either XSD or DTD. For JSON there is at least one draft for an official standard: JSON Schema. More information can be found on http://json-schema.org
By going through this API documentation page, is it possible to tell which database is being used in the backend?
Zomato API
MySQL would require a php file on the server to handle the requests, make queries, pack data in JSON format then send it back to the device. But in this case parameters are passed to .json files. Please advice
There is no way to "see through" to what the backend service actually used to provide you with the information you may query for. Are you sure you want to continue using this product? The site notes that Zomato will no longer be available to individuals, and that your API key will be disabled if you don't use it monthly.
I haven't read the specs for that particular API. But in general, is it possible to tell what database is being used on the back end by studying an API? No. That's the whole point of an API: It's supposed to shield the API-user from implementation details.
It's probably true that in many cases you could make reasonable guesses about what tools are being used on the back end. Like if you see that the API gives you a syntax for doing comparisons that looks exactly like the proprietary compare function used in Foobar SQL and not found in any other database product, that would be a strong clue. But even something like that wouldn't be proof. Maybe originally they were using Foobar SQL, then they switched to another database, but to maintain compatibility they wrote code to translate the Foobar SQL compare to standard SQL syntax.