I took a look at this question that seeks to address the issue of REST media-type explosion. One of the suggestions was to have a media-type that describes a collection of anything. So for example, we could have an application/vnd.collection+json which is a collection with well-defined semantics that can hold a list of references to other resources:
{
"size": "3"
"elements": [
{ "href" : "http://my.api.com/resource/1" },
{ "href" : "http://my.api.com/resource/2" },
{ "href" : "http://my.api.com/resource/3" }
]
}
I know an option to alleviate chattiness is to include embedded representations of resources. How would a "generic" media-type for lists accomplish that? Don't the semantics of the list change based on which embedded resource is inside it? This is especially relevant if embedded resources have different processing-rules (which would ideally be conveyed by the media type). Would be alright in this case to allow in-band information that describes the media type of the embedded resource? For example we could have application/vnd.collection+json for both links and embedded resources that do something like this:
{
"size": "3"
"element-content-type": "application/vnd.link+json"
"elements": [
{ "href" : "http://my.api.com/resource/1" },
{ "href" : "http://my.api.com/resource/2" },
{ "href" : "http://my.api.com/resource/3" }
]
}
and if it contains an embedded resource:
{
"size": "3"
"element-content-type": "application/vnd.resource+json"
"elements": [
{
"id": "1"
"name": "Cool Resource"
},
{
"id": "2"
"name": "Awesome Resource"
},
{
"id": "3"
"name": "Super Awesome Resource"
}
]
}
The assumption is that application/vnd.link+json and application/vnd.resource+json have been documented as well.
I thought about this a little bit more, and I think it is actually OK to include the content-type like that. The reason is, we already do this. In HTML the script tag has a type attribute that can be application/javascript or application/vbscript (for example). The provides the browser a hint as to how to process the content of that tag. Similarly, I think the content-type in the above example achieves the same purpose: it tells the client how to process the elements in the collection.
I wanted to update this answer some more. It appears that another way to do this is to use a rel. At least, this is how HAL does it. You can create a namespaced rel with a curie so that you end up resolving the rel to a URL that points to documentation about that resource. This way you have access to the documentation and that should tell you all you need to know about the resource(s).
Related
I did some research about how REST APIs work and how to link resources via hypermedia. Most of the examples about linking resources is related to the response of the server. But I wonder how to reference to other resources when a certain resource should be updated.
Let´s take the simple resource of a person living at a specific location:
/api/persons/alice
{
"name": "Alice",
"location": {
"id": 1,
"links": {
"self": "/api/locations/1"
}
}
}
Now I want to update the location to another existing location. But how do I represent that?
Would I:
refer to the id of the new location
PUT /api/persons/alice
{
"name": "Alice",
"location": 2
}
refer to the URI of the new location
PUT /api/persons/alice
{
"name": "Alice",
"location": "/api/locations/2"
}
anything else?
HTTP PUT has remote authoring semantics - you should think of the payload as being the new representation of a document, being manipulated by some general purpose HTTP aware document editor.
GET /api/persons/alice HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Alice",
"location": {
"id": 1,
"links": {
"self": "/api/locations/1"
}
}
}
PUT /api/persons/alice HTTP/1.1
Content-Type: application/json
{
"name": "Alice",
"location": {
"id": 2,
"links": {
"self": "/api/locations/2"
}
}
}
200 OK
The assumption here is that the consumer of your API is familiar with the schema here, and understands the semantics, which fields are optional, which are required, and so on.
(Getting this to work on a long time scale means investing effort in designing your schema well, choosing reasonable defaults, and so on).
Please observe this part of the PUT specification with care:
An origin server SHOULD verify that the PUT representation is consistent with any constraints the server has for the target resource that cannot or will not be changed by the PUT.... When a PUT representation is inconsistent with the target resource, the origin server SHOULD either make them consistent, by transforming the representation or changing the resource configuration...
...
An origin server MUST NOT send a validator header field (Section 7.2), such as an ETag or Last-Modified field, in a successful response to PUT unless the request's representation data was saved without any transformation applied to the body....
In other words, the server doesn't need to "store" the new representation as provided.
I am new to Dialogflow so my question may be too simple. However, I do not understand what is the purpose of naming actions in Dialogflow. I have watched videos on youtube and people in them are using actions when they have a webhook. For example they may have an if condition in their source code
(e.g. in python
if action == 'action_name':
...
)
which executes something particular in this case.
However the json output which is retrieved by the source code has the following form:
{
"id": "123d9e8e-314f-451b-8b15-5e3b55baa980",
"timestamp": "2018-03-16T17:03:05.987Z",
"lang": "en",
"result": {
"source": "agent",
"resolvedQuery": "Hello",
"action": "input.welcome",
"actionIncomplete": false,
"parameters": {},
"contexts": [],
"metadata": {
"intentId": "effe6b2b-3372-4f89-882f-ff937b2b2abb",
"webhookUsed": "false",
"webhookForSlotFillingUsed": "false",
"intentName": "Welcome"
},
"fulfillment": {
"speech": "Hello, how can I help you?",
"messages": [
{
"type": 0,
"speech": "Hello, how can I help you?"
}
]
},
"score": 1
},
"status": {
"code": 200,
"errorType": "success",
"webhookTimedOut": false
},
"sessionId": "491d57cb-0af2-45ac-a658-9e47ec6658ce",
"alternativeResultsFromKnowledgeService": {}
}
Since the json data contains the IntentName why to bother naming an unique action for this specific intent when you can get directly the name of the intent in your json?
I tend to think of this in two ways, depending on exactly what I'm building. (Or sometimes a combination of these two ways.)
The Intent Name is a human-usable name, while the Action is something that is more intended for use by the webhook and more directly maps to a function.
Since you can have more than one Intent use the same Action, it can be convenient to map a few different ways the user may say something (and the parameters they may send along with them) to the same method. While you could do that by listing all the different Intent names in your code, it is easier to do that on the Dialogflow side.
In truth - use whatever works best for you. I tend to name my Intents and my Actions very similarly, but do branching based on what makes the most sense for the code (which sometimes also includes other values that may be sent).
My question has some overlap with JSON schema for data description vs data validation vs input validation, but enough differences that I felt it warranted a new question.
I am trying to understand the best way to design one schema that is usable for validating input and output on a single resource representation. Here's an example.
{
"type": "object",
"properties": {
"id": {
"type": "number",
"readOnly": true
},
"title": {
"type": "string"
},
"post": {
"type": "string"
}
},
"required": ["id", "title", "post"],
"additionalProperties": false
};
The problem is that when validating output, we want id, title and post required. When validating input, one or more fields will not be required, and if they provide an id I want the validation to fail (due to the readOnly keyword)
I think the right way is to combine required with subschemas or boolean logic but I'm not sure exactly how to tie them together.
Is that the right path, or is there a better solution? Does anyone have an example that works with the latest version of JSON Schema (draft 7 at this time)
Thanks!
There are a couple of possible approaches here.
First, readOnly never causes JSON Schema's validation process to fail. It's not an assertion, just an annotation that applications can use to take action as they please. So your server application can handle that however it wants- raise an error if someone attempts to change it, or just silently ignore the new value.
Or look at the HTTP Prefer header and if handling=lenient is present, ignore any attempts to change read-only values ,but if handling=strict is present, error out on any attempts.
Or handle different fields differently. If you have a lastModified field and support an HTTP GET => modify => HTTP PUT workflow, then when you PUT a representation back, lastModified will inevitably be wrong but read-only at some point. You don't want to break PUT for an out of date auto-generated timestamp. But you probably do want to raise an error if someone thinks they can change the id field.
Given that, there are two general approaches: write a schema that works both ways and do additional checking in your application layer, or nail down everything for input and output separately.
The "works both ways" approach would remove id from required but document that, once created, a resource will always have an id. But this way it could be omitted on create or write without problems. To decide whether this is reasonable, think about the use cases for client-side validation of output. Do clients really need JSON Schema to check whether the server sent an id, or is that something that a client can reasonably assume, based on documentation, that the server will do correctly?
For the "lock down each way" approach, you could do something like this:
{
"definitions": {
"common": {
"type": "object",
"properties": {
"id": {
"type": "number",
"readOnly": true
},
"title": {
"type": "string"
},
"post": {
"type": "string"
}
},
"required": ["title", "post"],
"additionalProperties": false
},
"input": {
"allOf": [
{"$ref": "#/definitions/common"},
{"properties": {"id": false}}
]
},
"output": {
"allOf": [
{"$ref": "#/definitions/common"},
{"required": ["id"]}
]
}
}
}
You need to define id in the common schema so that "additionalProperties": false knows about it (I try to avoid "additionalProperties": false as it makes evolving representations in a compatible way difficult, but if you want to use it, this is how to make it work).
For output, just make id required.
For input, use {"properties": {"id": false}} to forbid id. Even though it's defined in "common", the false boolean schema will always cause id to fail validation on input.
Of course, then you have to figure out how your application knows which schema to use, because again readOnly on its own never causes validation to fail. This is one reason that I prefer to have one schema for both read and write and let the application handle the differences (and document how that handling works).
I'm using EventStore and want to post a message (event) to it. I use the HTTP API for testing purposes. I've managed to post the event itself, with an event type specified, but I can't figure out how to specify metadata for my event. (and I must provide this metadata because my consuming application on the other side expects it).
This is what my HTTP request looks like:
Content-Type: application/json
ES-EventType: My.own.event.type
POST http://10.0.75.2:2113/web/index.html#/streams/foobar
{
"props": "andvalues"
}
Do I specify metadata in the body in through headers? I can't find much docs about this, only the official that doesn't mention it.
The documentation mentions the full schema for an event being written. It looks like this:
[
{
"eventId" : "string",
"eventType" : "string",
"data" : "object",
"metadata" : "object"
}
]
For example:
[
{
"eventId": "fbf4a1a1-b4a3-4dfe-a01f-ec52c34e16e4",
"eventType": "event-type",
"data": { "a": "1" },
"metadata": { "b": "2" }
}
]
Note that it's an array, and that you must pass content-type as application/vnd.eventstore.events+json
Check this page, scroll to Event Store Events Media Type.
I have a page where I list the books of a school. The user can update a book, add a new book or delete an existing book. All actions must be saved when the form is submitted.
How can i map a rest API for that? I could take advantage of the endpoints i already have.
UPDATE
PUT /schools/1/books
{
"books": [
{
"id": "1",
"name": "Book 1"
}
]
}
CREATE
POST /schools/1/books
{
"books": [
{
"name": "Book 2"
},
{
"name": "Book 3"
}
]
}
DELETE
DELETE /schools/1/books
{
"books": [
{
"id": 2
}
]
}
But I need everything to run on the same transaction, and wouldn't make sense to submit 3 requests.
I also thought of creating a new endpoint where I would create books that doesn't exists, update books that exists, and remove books that are not present on the request.
So if this school has Book 1 and Book 2, I could update Book 1, create New Book and remove Book 2 with:
PUT /schools/1/batch-books
{
"books": [
{
"id": "1",
"name": "Updated Book 1"
},
{
"name": "New Book"
}
]
}
Do you guys have other options?
I would separate things into different resources:
/books and /books/{id} for books. They gives book details and allow to manage them.
/schools and /schools/{id} for schools. They gives school details and allow to manage them.
/schools/{id}/books to associate books in schools. I mean books that are available within a school. This resource provides methods to manage a list of links to books.
Let me detail the last resource. In fact, this is related to hypermedia. In the following, I'll use JSON-LD but you're free to use other hypermedia tools.
A GET method will return the list of associated books:
GET /schools/1/books
[
{
"#id": "http://api.example.com/books/1895638109"
},
{
"#id": "http://api.example.com/books/8371023509"
}
]
You can notice that you can implement mechanisms to allow to get more details if needed. Leveraging the Prefer header seems to be a great approach (see the link below for more details).
In addition, you could provide the following methods:
POST to add a link to the school. The request payload would be: {"#id": "http://api.example.com/books/1895638109"}. The response should be a 201 status code.
DELETE to delete a specific link from a school. A query parameter could be used to specify which link to remove.
PATCH to allow to do several operations in one call and actually provide some batch processing. You can leverage at this level JSON-PATCH for the request processing. Within the response, you could describe what happens. There is no specification at this level so you're free to use what you want... Here is a sample for the request payload:
PATCH /schools/1/books/
[
{
"op": "add", "value": "http://api.example.com/books/1895638109"
},
{
"op": "remove", "path": "http://api.example.com/books/8371023509"
}
]
Reading the following links could give you some hints on the way to design such use case:
Implementing bulk updates within RESTful services: http://restlet.com/blog/2015/05/18/implementing-bulk-updates-within-restful-services/
On choosing a hypermedia type: http://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
Creating Client-Optimized Resource Representations in APIs: http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html
Hope it helps you,
Thierry