Subject: [scim] Protocol vs API

From: Barry Leiba <[email-masked]>
Date: Wed, 9 Jul 2014 12:22:02 -0400

It seems y'all have a disagreement about whether you're proposing a
protocol or an API, and that the document is inconsistent about what
to call it.

I think this is clearly a protocol, and *not* an API.

As I see it, an API is something that says, "call this interface to do
this, and call that interface to do that."  Then people implement the
API in their libraries, and you use the appropriate library for the
platform you're programming for, and whatever.  APIs might connect to
proprietary stuff on the back end.

The WG's main document is actually specifying bits on the wire, not
programming interfaces.  Someone could certainly build in API around
this, but this isn't one.

Barry

---

From: Kelly Grizzle <[email-masked]>
Date: Wed, 9 Jul 2014 16:33:45 +0000

I don't know that I agree with this.  Wikipedia has the following to say on its API page:

     In some other cases, notably for SOAP and REST services, an API comes as just a specification of remote calls exposed to the API consumers.

This is pretty much what the SCIM API document does, and most things that I have seen call REST endpoint documentation an API.

That said ... I don't really care what we call it.  If we do decide to go with "protocol", it probably would make sense to rename the draft-ietf-scim-api draft to something else.

--Kelly

-----Original Message-----
From: scim [mailto:[email-masked]] On Behalf Of Barry Leiba
Sent: Wednesday, July 09, 2014 11:22 AM
To: [email-masked]
Subject: [scim] Protocol vs API

It seems y'all have a disagreement about whether you're proposing a protocol or an API, and that the document is inconsistent about what to call it.

As I see it, an API is something that says, "call this interface to do this, and call that interface to do that."  Then people implement the API in their libraries, and you use the appropriate library for the platform you're programming for, and whatever.  APIs might connect to proprietary stuff on the back end.

The WG's main document is actually specifying bits on the wire, not programming interfaces.  Someone could certainly build in API around this, but this isn't one.

Barry

_______________________________________________
scim mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/scim

---

From: Phil Hunt <[email-masked]>
Date: Wed, 9 Jul 2014 09:55:09 -0700

Ok. I see your distinction. You are defining “API” as exclusive to programming (how one accesses a protocol in code).

My distinction was really in the layers: bits in the app layer (e.g. payload) vs. bits related to a protocol on a network (IP).

I will make it consistent around protocol then.

Phil

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

---

From: Barry Leiba <[email-masked]>
Date: Wed, 9 Jul 2014 13:08:54 -0400

Kelly says that Wikipedia says...
>      In some other cases, notably for SOAP and REST services, an
>      API comes as just a specification of remote calls exposed to the
>      API consumers.

Remote calls, yes.  But here we're specifying bits on the wire.

I think that part of the issue with, say, SOAP is that SOAP mixes the
two, which blurs things.  To me, the part of SOAP that specifies the
bits on the wire is also a protocol.

This might also be a case of IETF idiom vs idiom used elsewhere.
To-MAY-to, to-MAH-to, or something like that.

Kelly, directly now...
> That said ... I don't really care what we call it.  If we do decide to go
> with "protocol", it probably would make sense to rename the
> draft-ietf-scim-api draft to something else.

The title of the document says "protocol", and at this point it's not
worth the trouble to change the filename.  The filename will disappear
(except in the document history in the datatracker) when the RFC is
published anyway.

Phil says...
> Ok. I see your distinction. You are defining "API" as exclusive to
> programming (how one accesses a protocol in code).

Right: Application Programming Interface.

> My distinction was really in the layers: bits in the app layer
> (e.g. payload) vs. bits related to a protocol on a network (IP).

In the IETF, at least, we refer to bits-on-the-wire at every layer as
"protocol".  IP is a protocol, BGP is a protocol, TCP is a protocol,
SMTP and HTTP are protocols, and various things built on HTTP are
(higher layer) protocols.

> I will make it consistent around protocol then.

T'anks!

Barry

---

From: Kelly Grizzle <[email-masked]>
Date: Wed, 9 Jul 2014 17:10:26 +0000

Works for me.  Thanks for the clarifications, Barry.

-----Original Message-----
From: scim [mailto:[email-masked]] On Behalf Of Barry Leiba
Sent: Wednesday, July 09, 2014 12:09 PM
To: [email-masked]
Subject: Re: [scim] Protocol vs API

I think that part of the issue with, say, SOAP is that SOAP mixes the two, which blurs things.  To me, the part of SOAP that specifies the bits on the wire is also a protocol.

Kelly, directly now...
> That said ... I don't really care what we call it.  If we do decide to 
> go with "protocol", it probably would make sense to rename the 

The title of the document says "protocol", and at this point it's not worth the trouble to change the filename.  The filename will disappear (except in the document history in the datatracker) when the RFC is published anyway.

Phil says...

> My distinction was really in the layers: bits in the app layer (e.g. 
> payload) vs. bits related to a protocol on a network (IP).

In the IETF, at least, we refer to bits-on-the-wire at every layer as "protocol".  IP is a protocol, BGP is a protocol, TCP is a protocol, SMTP and HTTP are protocols, and various things built on HTTP are (higher layer) protocols.

T'anks!

Barry