[Backend] Remove Response Envelopes

[JakeIsMeh]

Currently, the spec (both v1 & v2) call for all responses (and requests) to be enveloped in an object describing the resource.

{
  "article": {
    "title": "example",
    // the rest of the attributes
  }
}

This is not only redundant as the URI should indicate the resource that the endpoint receives and/or returns, but also an annoyance if you are trying to strongly type responses instead of constructing your response in an anonymous object.

For example, if I'm using ASP.NET Core, I might write something like this without enveloping:

[HttpGet("{id}")]
public ActionResult<ArticleDto> Get(int id) {
    return new ArticleDto(_articleCtx.Find(id));
}

However, due to the enveloping requirements, a wrapper type has to be created:

public class GetArticleDtoEnvelope {
    public GetArticleDto article { get; set; }
}

[HttpGet("{id}")]
public ActionResult<GetArticleDtoEnvelope> Get(int id) {
    return new GetArticleDtoEnvelope{ article = new GetArticleDto(_articleCtx.Find(id)) };
}

While not hard to do, it creates a useless type for each endpoint that returns a singular resource. Note that this only applies to singular resources. For endpoints that return a list of resources, it is understandable that for pagination purposes that it comes in an envelope containing pagination metadata.

[Aakash017]

Hello @JakeIsMeh I would like to work on this but I am new in open source contribution, so can you please help me ?

Thanks

[geromegrignon]

Hello,

@JakeIsMeh As I'm currently refactoring the Angular repo, i share your thoughts. I have been thinking about that for a while, about which path to follow (envelopes as a standard versus only for response with extra metadata like pagination), and by experimenting with it directly, keeping it as a standard adds complexity everywhere.

@Aakash017 This will be part of the new versions of the specs (as it would introduce a breaking change). I need to clean up the old v2 branch as there were a lot of changes on the main branch. Once done, I'll tag you for the contribution opportunity. I should be able to setup it up for this weekend.

[Aakash017]

sure @geromegrignon Thanks for the update

[geromegrignon]

@JakeIsMeh sorry I forgot about the project versions: the v2 has not been released yet. It's still in progress, and any change is welcome to improve it.

[geromegrignon]

@Aakash017

About open-source contribution, you can rely on the CONTRIBUTING file. If you have any questions or guidance requests, please use this discussion not to bother Jake with notifications here.

About the changes themselves, here are the affected parts:

• the openapi definition: https://github.com/gothinkster/realworld/blob/main/api/openapi.yml
• the API project (code and tests): https://github.com/gothinkster/realworld/tree/main/apps/api

There are some other affected parts but not ready for v2:

• frontend demo
• API Testing (requiring deploying the new API/setup the CI to do so)

Please tell me which parts you want to work on, and don't hesitate if you need support.