8000 Merge pull request #44 from glennblock/glennblock-patch-1 · evalcode/api-guidelines@f795f5c · GitHub
[go: up one dir, main page]
Skip to content

    • Commit f795f5c

    Browse files
    cleemullinscleemullins
    authored
    Merge pull request microsoft#44 from glennblock/glennblock-patch-1
    Replace usages of "object"
    2 parents c1af7ae + cfd2d37 commit f795f5c

    File tree

    1 file changed

    +9
    -9
    lines changed

    1 file changed

    +9
    -9
    lines changed

    ‎Guidelines.md

    Lines changed: 9 additions & 9 deletions
    Original file line numberDiff line numberDiff line change
    @@ -242,18 +242,18 @@ Below is a list of verbs that Microsoft REST services SHOULD support. Not all re
    242242

    243243
    Verb | Description | Is Idempotent
    244244
    ------- | -------------------------------------------------------------------------------------------------------------------------- | -------------
    245-
    GET | Return the current value of an object | True
    246-
    PUT | Replace an object, or create a named object, when applicable | True
    247-
    DELETE | Delete an object | True
    248-
    POST | Create a new object based on the data provided, or submit a command | False
    249-
    HEAD | Return metadata of an object for a GET response. Resources that support the GET method MAY support the HEAD method as well | True
    250-
    PATCH | Apply a partial update to an object | False
    245+
    GET | Return the current value of a resource | True
    246+
    PUT | Replace a resource, or create a named resource, when applicable | True
    247+
    DELETE | Delete a resource | True
    248+
    POST | Create a new resource based on the data provided, or submit a command | False
    249+
    HEAD | Return metadata of a resource for a GET response. Resources that support the GET method MAY support the HEAD method as well | True
    250+
    PATCH | Apply a partial update to a resource | False
    251251
    OPTIONS | Get information about a request; see below for details. | True
    252252

    253253
    <small>Table 1</small>
    254254

    255255
    #### 7.4.1 POST
    256-
    POST operations SHOULD support the Location response header to specify the location of any created object that was not explicitly named, via the Location header.
    256+
    POST operations SHOULD support the Location response header to specify the location of any created resource that was not explicitly named, via the Location header.
    257257

    258258
    As an example, imagine a service that allows creation of hosted servers, which will be named by the service:
    259259

    @@ -273,7 +273,7 @@ Where "server321" is the service-allocated server name.
    273273
    Services MAY also return the full metadata for the created item in the response.
    274274

    275275
    #### 7.4.2 PATCH
    276-
    PATCH has been standardized by IETF as the verb to be used for updating an existing object incrementally (see [RFC 5789][rfc-5789]). Microsoft REST API Guidelines compliant APIs SHOULD support PATCH.
    276+
    PATCH has been standardized by IETF as the verb to be used for updating an existing resource incrementally (see [RFC 5789][rfc-5789]). Microsoft REST API Guidelines compliant APIs SHOULD support PATCH.
    277277

    278278
    #### 7.4.3 Creating resources via PATCH (UPSERT semantics)
    279279
    Services that allow callers to specify key values on create SHOULD support UPSERT semantics, and those that do MUST support creating resources using PATCH. Because PUT is defined as a complete replacement of the content, it is dangerous for clients to use PUT to modify data. Clients that do not understand (and hence ignore) properties on a resource are not likely to provide them on a PUT when trying to update a resource, hence such properties MAY be inadvertently removed. Services MAY optionally support PUT to update existing resources, but if they do they MUST use replacement semantics (that is, after the PUT, the resource's properties MUST match what was provided in the request, including deleting any server properties that were not provided).
    @@ -283,7 +283,7 @@ Under UPSERT semantics, a PATCH call to a nonexistent resource is handled by the
    283283
    If a service does not support UPSERT, then a PATCH call against a resource that does not exist MUST result in an HTTP "409 Conflict" error.
    284284

    285285
    #### 7.4.4 Options and link headers
    286-
    OPTIONS allows a client to retrieve information about an object, at a minimum by returning the Allow header denoting the valid method verbs for this resource.
    286+
    OPTIONS allows a client to retrieve information about an resource, at a minimum by returning the Allow header denoting the valid method verbs for this resource.
    287287

    288288
    In addition, services SHOULD include a Link header (see [RFC 5988][rfc-5988]) to point to documentation for the resource in question:
    289289

    0 commit comments

    Comments
     (0)
    0