Subject: [scim] API comments: start to 3.2.2.2

From: Kelly Grizzle <[email-masked]>
Date: Mon, 21 Jul 2014 22:28:53 +0000

I'm going through the docs with a fine-toothed comb.  Here are my comments so far ... more to come later.

> 3.    POST  Create new resources, create a search request, or bulk modify
>       resources.

The other HTTP method descriptions use "retrieves", "modifies", "deletes".  Should this use "creates"?

> 3.  | Schema     | /Schemas           | GET (Section  | Retrieve a      |
>     |            |                    | 3.2.1)        | resource's      |
>     |            |                    |               | schema          |

I recommend changing the description to "Retrieve the supported schemas".

> 3.   Response and error codes SHOULD be transmitted via the HTTP status
>      code of the response (if possible), and SHOULD also be specified in
>      the body of the response.

Currently response codes are only included in the body of the response for errors.  Also, is there any case where transmitting an HTTP status code is not possible?  I recommend changing to the following:

       Response and error codes MUST be transmitted via the HTTP status
       code of the response.  Errors MUST be included in the body of the
       response (see section 3.10).

> 3.1  Clients that would like to override a
>      server defaults, MAY specify "null" for a single-valued attribute or
>      an empty array "[]" for a multi-valued attribute to clear all values.

Should "defaults" be "default" here?

> 3.1.1  the meta attribute
>        "resourceType" SHALL be set by the service provider to the
>        corresponding resource Type for the endpoint.

"resource Type" should be "resource type" (lowercase)

> 3.2   Service providers MAY choose to respond with a sub-set of
>       resource attributes, though MUST minimally return the resource id and
>       meta attributes.

Now that we specify "returned" in the schema (always/never/default/request), the first part of this sentence doesn't make as much sense.  Perhaps this should be changed to mention the "returned" attribute.

> 3.2.2.1  A server MAY support searches against the server root (e.g.  "/").

Didn't we talk about adding something to ServiceProviderConfigs that indicates whether this is supported or not?

> 3.2.2.2  Clients may request a subset of resources by
>          specifying the 'filter' URL query parameter containing a filter

It seems like most of the spec uses double-quotes rather than single quotes.  Should this made consistent?

---

From: Phil Hunt <[email-masked]>
Date: Tue, 22 Jul 2014 00:16:11 -0400

Agree on all your points.

Phil

@independentid
www.independentid.com
[email-masked]

On Jul 21, 2014, at 6:28 PM, Kelly Grizzle <[email-masked]> wrote:

> I’m going through the docs with a fine-toothed comb.  Here are my comments so far … more to come later.
>  
>  
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim