Subject: [scim] API comments section 3.5 to end

From: Kelly Grizzle <[email-masked]>
Date: Fri, 1 Aug 2014 03:13:04 +0000

Last set of comments for the API doc.

> 3.5  status  A complex type that contains information about the success
>              or failure of one operation within the bulk job.  REQUIRED in a
>              response.
>
>              code  The HTTP response code that would have been returned if a
>                 a single HTTP request would have been used.  REQUIRED.
>
>              description  A human readable error message.  REQUIRED when an
>                 error occurred.

Should the bulk response status attribute be updated to be more in line with the updated error response (status, scimType, and detail sub-attributes)?

> 3.5    If a bulk job is processed successfully the HTTP response code 200 OK
>        MUST be returned, otherwise an appropriate HTTP error code MUST be
>        returned.

A 200 is returned even if some of the operations failed, correct?  Might be worth clarifying.

> 3.5 The client MAY override
>     this behavior by specifying a value for failOnErrors attribute.

Change to "for the failOnErrors attribute".

> 3.5 A location attribute that includes the
>     resource's end point MUST be returned for all operations excluding
>     failed POSTs.

Typo.  Change "end point" to "endpoint".

> 3.5  The following example shows how to add, update, and remove a user.
>      ...
>      The service provider returns the following response.
>      ...
>         {
>             "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
>             "method": "POST",
>             "bulkId": "qwerty",
>             "version": "W\/\"oY4m4wn58tkVjJxK\"",
>             "status": {
>                 "code": "201"
>             }
>         },

The text above says the following regarding creating a new resource:

  the service provider MUST return the same bulkId together with the newly
  created resource.

It seems like the example response should include the full resource.  Would this fit in the "data" sub-attribute?  If so, the description of the "data" sub-attribute should be changed to indicate this.  Same comment for other bulk examples that contain POSTs.

> 3.5  The following example creates a User with the userName 'Alice' and a
>      Group with the displayName 'Tour Guides' with Alice as a member.
>      ...
>            "members": [
>             {
>               "type": "user",
>               "value": "bulkId:qwerty"
>             }
>           ]

The type should be "User" since the canonical values for type on member are capitalized (see schema in section 11.7 of schemas draft).

> 3.5            "members": [
>               {
>                 "type": "group",

Same comment as above ... need to capitalize "Group".

> 3.5  The following example the client sent a request exceeding the service
>      provider's max payload size of 1 megabyte.
>      ...
>      HTTP/1.1 413 Request Entity Too Large
>      Content-Type: application/scim+json
>      Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8

This response includes a Location header with a unique ID.  Do bulk requests have unique IDs and locations?  If not, the location should be removed

> 3.6 MAY specify the desired response data
>     format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g.,
>     "Accept: application/scim+json" or via URI suffix; e.g.,
>
>      GET /Users/2819c223-7f76-453a-919d-413861904646.scim

It seems like we shouldn't need to support URI suffixes anymore since JSON is the only supported format.

> 3.7   The defaut attribute set are those attributes whose schema have

Typo on "defaut".

> 3.7     GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
>         ...
>         Accept: application/json
>         ...
>         HTTP/1.1 200 OK
>         Content-Type: application/json

This example uses application/json for the Accept and Content-Type headers.  Should change this to application/scim+json.

> 3.10  The following attributes are defined inclusion in a SCIM error response
>       using a JSON body:

Not sure what the text is supposed to be here, but "defined inclusion" doesn't make sense to me.  Maybe "The following attributes are included in a SCIM error response using a JSON body"?

> 3.10  status
>         The HTTP status value (e.g. 400).  REQUIRED

We should indicate that this is an integer.

> 3.10    Implementers SHOULD handle the identified errors as described below

307 and 308 statuses are not really errors.  Should they be included here?

> 3.10  tooMany   a filter such as "userName eq "*"" would return all entries with a "userName"

The wildcard operator is not supported.  This filter should be "userName pr".

> 3.12    Content-Type:  application/json

Examples in this section are not using application/scim+json for Content-Type.

> 6.2  A detialed error,
>      "confidential_restricted" may be returned indicating the request must
>      be submitted using POST.

Typo on "detialed".  Also, should this error code be made into a scimType and use the camelCase convention used for other scimTypes?  The example in this section could be rewritten as:

   {
     "schemas": ["urn:scim:api:messages:2.0:Error"],
     "scimType":"confidentialRestricted"
     "detail":"Query filter involving 'name' is restricted or confidential",
     "status":403
   }

> 7.1 SCIM services may be offered by web applications wishin to offer

Typo on "wishin".