Ссылки на связанные ресурсы в методе API Post

Question

Я создаю конечную точку API, которая создает сообщение:

POST > /posts

Каждое сообщение может иметь до одной категории и несколько тегов.

При создании сообщения мне нужно ссылаться на его категорию и теги, если таковые имеются:

1. Для ссылки на категорию обычно я отправляю CategoryId;
2. Для ссылки на теги обычно я отправляю имена тегов, потому что некоторые из них могут быть новыми.

Так что мой Json будет что-то вроде:

{
  "title": "Some title",
  "content": "Some content",
  "categoryId": 1,
  "tagsNames": ["adventure", "drama"]
}

Или я должен разрешить, в качестве опции, ссылаться на категорию по имени и теги по идентификаторам:

{
  "title": "Some title",
  "content": "Some content",
  "categoryName": "books",
  "tagsIds": [1, 2]
}

Чтобы не иметь разных конечных точек, я мог бы использовать следующее:

{
  "title": "Some title",
  "content": "Some content",
  "category": {
    "id": 1,
    "name": null
  },
  "tags": [
    {
      "id": null,
      "name": "adventure"
    },
    {
      "id": null,
      "name": "drama"
    }
  ]
}

Затем сервер определяет, как ссылаются на категорию и теги: по идентификатору или имени.

Есть ли для этого стандарт?

Answer 1

То, как ссылаются на категорию и теги, зависит от модельных отношений между параметром, категорией и тегами. Например

Если модель отношений, как показано ниже:

public class Post
{
    public int PostId { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public Category Category { get; set; }
    public List<Tag> Tags { get; set; }
}

Примечание: json может использовать следующее: вы должны сделать так, чтобы идентификатор тега обнулялся следующим образом public int? TagId { get; set;}

{
"title": "Some title",
"content": "Some content",
"category": {
"id": 1,
"name": null
},
"tags": [
{
  "id": null,
  "name": "adventure"
},
{
  "id": null,
  "name": "drama"
}
]
}

Если модель отношений, как показано ниже:

public class Post
{
    public int PostId { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }

    public int CategoryId { get; set; }
    public List<string> TagsNames { get; set; }
}

JSON, который вы можете написать так:

{
"title": "Some title",
"content": "Some content",
"categoryId": 1,
"tagsNames": ["adventure", "drama"]
}

Answer 2

Есть ли стандарт для этого?

Ну, для этого нет стандарта. Выберите подход, который более понятен для вашего API, и убедитесь, что его свойства задокументированы.

Но как только вы представляете отношения, имеет смысл использовать идентификаторы. Если имена уникальны (и они не изменятся), они могут быть использованы для идентификации ваших ресурсов.