Restful Service и Generic Media Type Payload and stay HATEOAS

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

1. Зависит от вашей аудитории. Используйте то, что им будет проще всего потреблять. Являются ли они универсальными автоматическими агентами, которые могут понимать схему, или они являются разработчиками, работающими специально для вашего API. В любом случае вам всегда будут нужны удобочитаемые документы, поэтому я бы начал с этого. Если вы решите принять application/x-www-form-urlencoded тело запроса, то HTML-форма будет отличным способом предоставления рабочего шаблона.
2. Это определяет «тип» поля. Итак, name is a foaf:name говорит вам, что поле с именем name содержит значение типа http://xmlns.com/foaf/0.1/name. Вы должны прочитать о RDF, формате описания ресурсов, и посмотреть на представления, такие как Turtle и N3, которые должны прояснить это. Концепция отношений, которые являются URI (вместо простых строк), исходит оттуда, хотя отношения ссылок — это не то же самое, что свойства RDF, такие как owl:sameAs или foaf:name. Оба представлены ребрами в ориентированном графе.
3. Пожалуйста, объясните подробнее, вы имеете в виду добавленные/удаленные поля или совершенно другой тип контента? Я бы сказал, что последний является другим ресурсом и должен иметь другой URI. Ваши клиенты должны будут либо понимать, либо иметь возможность игнорировать любые будущие изменения, которые вы вносите в свои ресурсы.
4. Все предложенные вами типы контента должны развиваться таким образом. Это именно предпосылка HATEOAS.

Ваш дизайн кажется мне простой древовидной структурой с одним корневым ресурсом, содержащим список коллекций, каждая из которых содержит список конечных ресурсов. Кажется, я что-то здесь упускаю, потому что в этом нет ничего сложного.

Я собираюсь предположить, что под кандидатом вы подразумеваете человека, подающего заявку на работу, а под адресом вы подразумеваете место, где он живет или работает (в отличие, скажем, от адреса электронной почты). Кое-что из приведенного ниже может быть очевидным, но я включаю его для других читателей, которые могут столкнуться с этим вопросом.

Пример реализации с использованием HAL:

Запрос:

GET / HTTP/1.1
Host: example.com
Accept: application/hal+json

Ответ:

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/" },
    "http://example.com/docs/applicant": [
      { "href": "/applicant1" },
      { "href": "/applicant2" },
      { "href": "/applicant3" }]
} }

Затем клиент будет искать гиперссылки, которые имеют отношение http://example.com/docs/applicant, которое является просто строкой и может быть fishmonkeygiraffe, если вы хотите. Преобразование строки в URL-адрес http позволяет разработчикам клиента легче находить вашу документацию, а также связывать области видимости с помощью префикса это с уникальной строкой: ваш собственный домен. Формат ответа может быть любым форматом с поддержкой гипертекста, например HTML, при условии, что клиент знает, как найти внутри него гиперссылки (элементы ‹LINK> и ‹A>), или вы можете вернуть их в заголовке HTTP Link, но тогда клиент несет ответственность за их хранение, если ему нужно записать извлеченный ресурс на диск.

Затем клиент запрашивает тот, на который он хочет посмотреть:

GET /applicant1 HTTP/1.1
Host: example.com
Accept: application/hal+json

Ответ:

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/applicant1" },
    "http://example.com/docs/applicant-address": [
      { "href": "/applicant1/address1" },
      { "href": "/applicant1/address2" },
      { "href": "/applicant1/address3" }]
} }

Очевидно, что «заявитель1» может быть чем угодно, например. "претенденты/1" или "вакансии/sweet-менеджер/кандидаты/дэйв-смит". Клиент просто переходит по указанному URL-адресу.

Затем клиент выбирает гиперссылку типа http://example.com/docs/applicant-address для получения:

GET /applicant1/address1 HTTP/1.1
Host: example.com
Accept: application/hal+json

Ответ:

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/applicant1/address1" },
    "edit-form": { "href": "/applicant1/address1/edit" },
    "http://example.com/docs/applicant": { "href": "/applicant1" }
  },

  "street": "5 Dungeon Drive",
  "town": "Snotty Hill",
  "county": "London",
  "postcode": "NE5 2LT",
  "country": "GB",
}

Теперь клиент хочет изменить адрес, поэтому он переходит по гиперссылке с отношением «форма редактирования»: (см. отношения связи IANA)

GET /applicant1/address1/edit HTTP/1.1
Host: example.com
Accept: text/html

Ответ:

HTTP/1.1 200 OK

<!DOCTYPE HTML>
<form action="/applicant1/address1" method="POST">
  <input name="street" value="5 Dungeon Drive">
  et cetera
</form>

В результате чего:

POST /applicant1/address1 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

street=5%20Dungeon%20Drive&...

Я использовал HAL, потому что HAL похож на JSON-версию XML + XLink, просто его проще вводить в примерах SO;), то есть это общий формат синтаксического анализа с поддержкой гипермедиа, не более того. Все взаимодействие управляется связными отношениями. Веб-браузеры знают, что делать со ссылкой rel="stylesheet", потому что они знают, что означает это отношение. Приведенный выше список отношений ссылок, определенный IANA, — это те, которые вы должны выбрать в первую очередь (очень полезны item и collection), а затем, если то, что вы ищете, недостаточно конкретно, попробуйте найти общедоступный список отношений ссылок, относящихся к вашего сектора (например, посмотрите, какие API публикует лидер рынка) и повторно используйте их, если это возможно. Это позволит инструментам стать интероперабельными, поскольку все они ищут одни и те же отношения ссылок. Ваш пример Dublin Core в вопросе представляет собой аналогичный репозиторий публично определенных свойств RDF.

Для гиперссылок связь (контракт) заключается не между клиентом и вашим сайтом, а между клиентом и набором отношений. Отношения должны быть как можно более известными (это то, что имеет в виду Википедия, когда говорит «общее понимание гипермедиа»).
Для полей ресурсов, если вы хотите, чтобы ваш ресурс Решение на основе RDF, использующее известные свойства RDF, которые тесно связаны с вашей сферой бизнеса. Существует несколько сериализаций RDF в JSON, но на данный момент нет явного лидера. На данный момент вам, вероятно, будет лучше поддерживать только XML. Сообщение в блоге Шесть простых шагов из JSON в RDF могут оказаться полезными для изучения основ RDF.