Set an Accept header in the HTTP request

[collimarco]

Describe the error in the specification

Some common web frameworks, like Laravel or Rails, decide what type of response to provide based on the Accept header of the HTTP request.

For example in Rails you may have:

def destroy
  @post = Post.find params[:id]
  @post.destroy
  respond_to do |format|
    format.html { redirect_to posts_path }
    format.json { head :no_content }
  end
end

If you are building an OpenAPI spec to deal with that Rails API, you need to specify this in the request:

Accept: application/json

Otherwise, without that header in the request, the default response type is HTML and you will get a HTML response (or a redirect in this case) instead of the 204.

Additional context

This issue is even more serious since you cannot set the required header explicitly, due to this sentence in the OpenAPI official specification:

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

[handrews]

@collimarco I believe there are two reasons for that restriction:

1. The media types (or ranges) expected to be usable in Accept are specified as keys under content field of the Response Object. Typically the Response Object under a "200" or similar status where the response is a representation of the resource. By default, a tool would just put all of those in Accept in some implementation-defined order (because JSON objects are not guaranteed to preserve key order).
2. An OpenAPI Description (OAD) describes the known usable API surface. A client is free to set whatever Accept they want. The restriction is only on having a Parameter Object with in: header, name: Accept. But a client or application can set whatever they want. An OAD might advertise both JSON and XML responses, for example, but the application may only understand JSON and set Accept: application/json accordingly.

Does that make it more clear?

[collimarco]

The media types (or ranges) expected to be usable in Accept are specified as keys under content field of the Response Object.

Yes, I already know that. The point is that you may have a successful status code like 204 that doesn't expect a content in the response. So you don't have a way to specify the Accept header in the request in that case! For example:

responses:
  '204':
    description: Resource was successfully deleted.
    # there is no response body here, so we cannot specify application/json, so the Accept header is not set in the request
    # so Rails and other frameworks will respond in HTML format (or a redirect in my original Rails example)

This is not a Rails bug. Normally in HTTP you can specify a Accept header in the request to ask a specific response format to the API request. Not supporting that is a major bug in the OpenAPI-Specification. The current specification is mixing and confusing the Content-Type of the response with the Accept header of the request.

If an API needs a specific Accept in the request in order to work properly, it should be possible to describe that with OpenAPI.

By default, a tool would just put all of those in Accept in some implementation-defined order (because JSON objects are not guaranteed to preserve key order).

That is an additional issue with the current specification. You have an Accept header that is totally unpredictable, unordered and can be different depending on the tool implementation. The response of an API can obviously change based on the Accept header of the request: so you absolutely need to have a way to specify that in some way.

a client or application can set whatever they want.

And that is an issue. They should not be free to "set whatever they want". Sometimes you need to specify (in the specification) what they MUST request in order to comply to the API contract.

[handrews]

@collimarco Why do you need Accept with a 204 response which has no content? To the extent that it is meaningful, it would apply to the representation you would get in a 200 response to a GET, and would only affect the metadata headers of the 204 response (this is from RFC9110 §15.3.5.

I am also questioning why, given that neither OpenAPI nor Rails are new technologies, this has never come up before if this is as fundamental of a problem as you say.

Is the code in your original post code that you wrote, or is it code deep in the framework that you cannot change?

[collimarco]

Why do you need Accept with a 204 response which has no content? To the extent that it is meaningful, it would apply to the representation you would get in a 200 response to a GET, and would only affect the metadata headers of the 204 response

As I wrote in the previous message, I am talking about the Accept header in the HTTP request. I am not talking about the response.

I simply need to set an Accept header (application/json) in the request, so that Rails responds in the correct format. This is not currently possible with OpenAPI.

this has never come up before

I found several reports online about this issue, but they don't have any answer.

Is the code in your original post code that you wrote, or is it code deep in the framework that you cannot change?

That code is very common in Rails applications, it's generated by Rails scaffolding and is a common practice. The API has been there for many years, but we are now adding an OpenAPI specification (so we cannot change the API, also because it's not an error in the API). The API simply expects an Accept header in the request in order to answer with the correct format.

[handrews]

@collimarco yes, I know we are talking about the request. Why would you send an Accept header when you do not expect content at all? The Accept header is about the representation of the resource, and when you expect a 204 you don't have a representation to care about.

That code is very common in Rails applications, it's generated by Rails scaffolding and is a common practice. ... The API simply expects an Accept header in the request in order to answer with the correct format.

So send one. I still don't understand what's stopping you from sending one.

[collimarco]

Why would you send an Accept header when you do not expect content at all?

In the Rails example above, if you don't send Accept: application/json in the request, you will get a redirect (format.html { redirect_to posts_path }) instead of the correct response (format.json { head :no_content }). You can also see the relevant Rails documentation here: https://api.rubyonrails.org/classes/ActionController/MimeResponds.html#method-i-respond_to

I still don't understand what's stopping you from sending one.

I could add an Accept header in the request specification, but OpenAPI says that "the parameter definition SHALL be ignored" in this case. So the tools that use the OpenAPI spec would ignore my Accept header added to the request.

[handrews]

I could add an Accept header in the request specification, but OpenAPI says that "the parameter definition SHALL be ignored" in this case. So the tools that use the OpenAPI spec would ignore my Accept header added to the request.

That's not what that "SHALL be ignored" means. That requirement means that a Parameter Object that has in: header, name: Accept SHALL be ignored because there is no need for one. It emphatically does not mean that, at runtime, when using the API, you can't add an Accept header. That requirement is there because if such Parameter Objects were allowed, they might conflict with the media types in the Response Objects and create an ambiguous description.

Again, adding an Accept header to the HTTP request at runtime is most definitely allowed and any implementation that fails to allow it is wrong, and a bug should be filed against it.

[collimarco]

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0

paths:
  /posts/{id}:
    delete:
      summary: Delete a post
      description: Deletes a post by its unique ID.
      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the post to delete
          schema:
            type: string
        - in: header # will this be ignored by tools that respect the OpenAPI standard?
          name: Accept
          required: true
          schema:
            type: string
            enum: [application/json]
      responses:
        '204':
          description: Post successfully deleted (no content returned)
        '404':
          description: Post not found

1. So the above specification with the Accept header is perfectly valid and compliant with the OpenAPI standard?
2. The Accept header defined in the above specification MUST be respected by tools that support the OpenAPI standard?

[handrews]

@collimarco No, you cannot have a Parameter Object with in: header, name: Accept because it it not necessary to have one in order to use the Accept HTTP header. Which is what I said before and clearly did not come across well, so I'm going to tag @OAI/tsc and bow out (I'm on vacation for the next week starting in a few hours and won't be on GitHub).

[ralfhandl]

@collimarco Your use case seems to be something that signatures could solve in the next major OpenAPI version aka Moonwalk, see

• Indicate the signature mechanism for the API sig-moonwalk#16

You would define two signatures with the same URI template and HTTP method, and different values for the Accept header:

• The signature with value application/json would return 204 No Content.
• The signature with value text/htmlwould return 200 Ok or a 3xx redirect.

Would you mind adding this use case to the signatures discussion and closing the issue here?

[collimarco]

you cannot have a Parameter Object with in: header, name: Accept because it it not necessary to have one in order to use the Accept HTTP header

@handrews Ok, clients can set an Accept header freely, but that is not the point. I need to document in the OpenAPI specification that the client MUST always include the Accept: application/json header in the request, and currently you can't do that. This is a major issue in the current specification.

@ralfhandl The HTML response is meant for browsers. The JSON response is meant for the API, and I need to document only this in the OpenAPI spec. I don't need to document the two versions.

[ralfhandl]

The JSON response is meant for the API, and I need to document only this in the OpenAPI spec. I don't need to document the two versions.

@collimarco Even if you only want to document the JSON response in the OpenAPI Description of your API, that is not possible with OpenAPI 3.x and planned for OpenAPI 4.0, which is why I kindly ask you to add your use case to the 4.0 discussion and close this 3.x issue.

Thanks in advance!

[karenetheridge]

In the Rails example above, if you don't send Accept: application/json in the request, you will get a redirect (format.html { redirect_to posts_path }) instead of the correct response (format.json { head :no_content }).

That sounds like a bug in the code then. If the API documentation clearly says that a 204 No Content response is one of the potential responses, then the code ought to be able to handle a request that doesn't have an Accept header (because the client isn't interested in accepting any response body!) Insisting upon an Accept header to send a 204 No Content response is just wrong.

I could add an Accept header in the request specification, but OpenAPI says that "the parameter definition SHALL be ignored" in this case. So the tools that use the OpenAPI spec would ignore my Accept header added to the request.

This is a case where the OpenAPI document and the implementing code are in conflict. I don't see how any of this is an issue with the OpenAPI specification.

[collimarco]

Insisting upon an Accept header to send a 204 No Content response is just wrong.

@karenetheridge No, it's not wrong. It's perfectly valid (and it's also a common practice in Rails). Find a single standard (outside your OpenAPI spec) that says that it is invalid. The Accept header in the request simply tells the application code to return a response in JSON format instead of responding in HTML format. How is that invalid?

If I set Accept: application/json in the request, is it valid for the HTTP standard if the server returns a 204 No Content?

Yes, that’s valid according to the HTTP standard.

• The Accept: application/json request header tells the server: “If you send a response body, I would like it to be JSON.”
• A 204 No Content response by definition has no response body (RFC 9110, section 15.3.5).
• Since there is no body, the content negotiation headers (Accept, Content-Type) are essentially irrelevant, there’s nothing to encode or type.

So, it is completely valid for the server to respond with 204 No Content even when the client sent Accept: application/json.
The only thing to avoid is including a Content-Type header or a body in the 204 response, since the spec forbids a body in this case.

[ralfhandl]

The Accept header in the request simply tells the application code to return a response in JSON format instead of responding in HTML format.

@collimarco As said above, you cannot express in OpenAPI 3.x that

• the client needs to send Accept: application/json in order to get a 204 No Content response.

I do not see a way to add that to OpenAPI 3.x, and it seems a valid use case for signatures in OpenAPI 4.0.

Please add it to the signatures discussion to make sure that this use case is not overlooked when designing OpenAPI 4.0.

[handrews]

@collimarco I moved this to a discussion as a precursor step to migrating it to OAI/sig-moonwalk but GitHub is not letting me transfer it at the moment. I'll try again later or see if some permissions have gotten messed up, but I just wanted to explain the conversion.