规范原文引用 (Clause 4.5.1):
A resource representation is a serialization of the resource state in a particular content format. It’s included in the data frame of an HTTP request or response. Representation header fields provide metadata about the representation.
规范原文引用 (Clause 4.5.2):
In HTTP requests and responses, the “Content-Type” HTTP header field is used to signal the format of the actual representation included in the data frame. If the format … is not supported by the server, it responds with the “415 Unsupported Media Type” response code.
For GET method, the “Accept” HTTP header of the HTTP request signals the content formats that a client supports. If the server cannot provide any of the accepted formats, it returns the “406 Not Acceptable” response code.
深度解析:
这是一场由HTTP头驱动的客户端与服务器之间的“语言协商”:
Content-Type(我发的是什么): 当客户端用POST或PUT发送数据时,用这个头告诉服务器“我发给你的是JSON格式的数据”。如果服务器(比如小王的NIAF)只接受JSON,但收到一个Content-Type: application/xml的请求,它必须拒绝,并返回415 Unsupported Media Type错误。
Accept(我想要什么): 当客户端用GET获取数据时,用这个头告诉服务器“我希望你返回JSON格式的数据给我”。如果服务器只能返回XML,而客户端的Accept头里没有application/xml,服务器就应该返回406 Not Acceptable错误。
NIAF → OAM: HTTP/1.1 201 Created
这里的ID supi-12345是由OAM(客户端)指定的。
4.6.1.1.2 读取资源 (Reading a Resource)
使用GET方法,操作必须是安全的(不改变资源状态)。
规范通过Figure 4.6.1.1.2.1-1: Reading a resource 和 Figure 4.6.1.1.2.2-1: Query of a collection of resources 进行了图示。
读取单个资源:GET一个具体的资源URI。
查询资源集合:GET一个集合URI,可以使用查询参数进行过滤。
小王的应用场景:
读取单个任务: GET /nniaf-analytics/v1/analytics-jobs/job-a8b3f→ 返回200 OK和该任务的JSON表示。
查询所有已完成的任务: GET /nniaf-analytics/v1/analytics-jobs?status=COMPLETED→ 返回200 OK和一个包含所有已完成任务的JSON数组。
规范原文引用 (Clause 4.6.1.1.2.2 NOTE):
The result array/empty array can be defined as an attribute of an object, if the service operation returns an object in the response content for extensibility consideration.
规范通过Figure 4.6.1.1.4-1: Deleting a resource 进行了图示。
成功后,必须返回204 No Content,响应体必须为空。
小王的应用场景:
AMF要删除已完成的任务job-a8b3f。
DELETE /nniaf-analytics/v1/analytics-jobs/job-a8b3f
NIAF成功删除后,返回一个不带任何消息体的204 No Content响应。如果AMF重试这个DELETE请求,NIAF因为已经删除了,找不到资源,此时它应该返回404 Not Found或者同样返回204 No Content以体现幂等性(具体行为由API定义)。
小王的应用场景(复用Part 1的例子):
需要一个接口“激活”某个处于“暂停”状态的监控配置。
POST /nniaf-analytics/v1/monitoring-configs/supi-12345/activate
这个activate就是一个自定义操作。
4.6.1.3 异步操作 (Use of Asynchronous Operations)
用于处理耗时很长的请求,避免客户端长时间阻塞等待。
规范原文引用 (Clause 4.6.1.3):
…if the NF service consumer when sending a request cannot expect to receive an immediate final response, the service consumer may provide a callback reference for final result notification. The service provider, … may then return an immediate “202 Accepted”, and notify the service consumer about the final result using the received callback reference at a later point in time.
Q3:为什么DELETE成功后要返回204 No Content而不是200 OK?
A3:这是HTTP语义的最佳实践。204 No Content明确地告诉客户端:“你的请求已成功处理,但服务器没有任何信息需要返回给你”。对于DELETE操作,资源已经被删除了,服务器确实没有该资源的信息可以返回了。如果返回200 OK,通常意味着响应体中会包含一些信息(即使是空的JSON对象{}),这会给客户端带来困惑,并浪费少量网络带宽。204是最精确、最干净的表示方式。