Что означает '*' и (n) возможное значение в спецификации параметра интерфейса REST?

Question

Контекст:

С учетом спецификации сервиса REST. Операции службы будут обслуживать данные SharePoint во внешних системах. Прежде чем спросить создателя спецификации. чтобы сделал некоторые уточнения, я хотел бы уверен, что не пропустите ни одной тривиальной конвенции ...

Вопрос:

Как интерпретировать эту спецификацию параметров?

Параметры: PartNumber *, SERIALNUMBER (п) *, CategoryNumber (дополнительный критерий поиска), описание (необязательно условие поиска)

Мои мысли до сих пор:

Первый Я думал, что «*» означает, что параметр является необязательным, со значением «все». Это соотносится с соглашением C# WCF опционного параметра пути REST и также коррелирует с соглашением по поиску SharePoint (где * означает: все)

Однако спецификация интерфейса использует «(необязательный термин поиска)» для CategoryNumber, поэтому я предполагаю, '*' не может означать то же самое ...

Также: Что может быть значением «(n)» в «SerialNumber (n) *»?

Answer 1

Учитывая службы REST спецификации

Согласно Оксфордскому словарю английского языка, definition слова спецификации является:

Акт определения что-то точно или в которой говорится об точный требование

Я не думаю, что это соответствует.

Это следующие параметры: путь, тело запроса, строка запроса или их комбинация?

Это очень неортодоксальный метод документации и в основном невозможно интерпретировать.

Вместо того, чтобы производить такую ​​неоднозначность, провайдер API, должен использовать один из стандартных форматов спецификации API, такие как OpenAPI (Swagger), RAML или API Blueprint.

Столкнувшись с вашей ситуацией, я бы не стал беспокоиться о том, чтобы просить разъяснений.

Фактически, я бы сказал провайдеру API, что этот уровень документации полностью неудовлетворителен.

По умолчанию я полагаю параметры пути, где можно

Хорошо, моя догадка будет:

Все эти параметры тела. Полезная нагрузка запроса POST будет что-то вроде:

{ 
    "PartNumber":"*", 
    "SerialNumber":"6786,9879,8979" 
} 

Причина этого -

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

Таким образом, * являются просто условиями запроса подстановочных знаков.

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

Дело в том, что я совершенно неправ, так что дайте разъяснения.