As I understand it, CalDAV is an extension to WebDAV to manage iCalendar subscriptions.
And Webcal is a URL scheme that does the same thing, but not standarized.
I'm I right here?
Whats the pros/cons for going either way?
All what Julian said, but presumably the real question is about the difference between plain iCalendar-over-HTTP (commonly called webcal, 'iCalendar subscription' or 'subscribed calendar') and CalDAV. Or in other words: what does CalDAV add.
Simply put: in iCoHTTP you usually store a whole calendar under one URL,
like 'http://yahoo.com/sports/nba/schedule-2015.ics' (or webcal:). This URL
represents a full calendar and is almost always readonly (you can't do a PUT to this URL). Why is that? Because to add/change/delete a single event in such a calendar, you would need to re-transfer the full calendar.
In CalDAV a calendar is a WebDAV collection, there is one URL which represents the calendar, e.g.: 'http://icloud.com/calendars/joe/home/' and then you have one child URL for each event. Like 'http://icloud.com/calendars/joe/home/buy-beer.ics', 'http://icloud.com/calendars/joe/home/family-meeting.ics' and so on. You can then just DELETE, PUT etc individual items of such a collection.
In summary:
If you simply want to publish a calendar which rarely changes and is managed by other means (like a CMS), you can use iCal-over-HTTP.
If you want to provide a calendar which the user (or maybe a group of people) can change from within their calendar client, you want to use CalDAV.
CalDAV also has a set of extensions, e.g. many CalDAV server can automatically perform scheduling operations for you (setting up meetings and such). There is an extension to share calendars with other people, and so on.
P.S.: This is a bit confusing, but yes, Apple also has a way of using WebDAV to manage iCalendar subscriptions. But this is yet another thing which works alongside CalDAV.
CalDAV is a protocol, extending WebDAV, thus HTTP.
Webcal is a URI scheme that AFAIK was invented by Apple and has exactly the same semantics as "http", except that Safari (and maybe some other browsers) know that the URI refers to a calendar, and thus invoke the "right" application without having to fetch the resource.
(Of course the right thing would have been just to inspect the media type (content-type header field) and then to invoke the matching application.
So this is an anti-pattern (done again by Apple with "itms" URIs).
Related
iCalendar has a UID field which is a universal identifier. It's intended to be unique value so the same event can be recognized when syncing or trying to add the same event twice. They're usually randomly generated, eg. a37c3632-3c26-4543-b91d-355a1b668a3a.
I'm tempted to use a URL describing the event as my UID. Is there any reason this isn't a good idea?
While strictly speaking this may not be forbidden, if you do care about interoperability, you are always taking a risk by not following common practices. There will be some client or server out there which will choke on your events. For example, some CalDAV servers tend to use the UID value as the last segment in CalDAV resource URLs. With your type of UID, they will need to URI encode that last segment, which some of them may fail to do.
Of course you can always put the blame on those bad implementations but, at the end of the day, it will be your users who will be unable to see your events.
There are new recommendations for the UID property which were published as part of RFC 7986 (see https://www.rfc-editor.org/rfc/rfc7986#section-5.3 ). Although the main purpose of this section is to allow use of UID in VCALENDAR, the recommended format make sense in all cases.
I would use a URL or X- property to convey your URL if you do care about it.
I'm building a REST service where I want to implement a way to deprecate certain URIs when they shouldn't be supported anymore for one reason or another. As functions are deprecated, they will be replaced by new ones that work in similar (but not identical) ways. This means that at some point, I will have to start responding with 410 Gone.
The idea is that all client software should be updated, and after say six months all users should have had the chance to upgrade. At this time, the deprecated URIs will start to inform the client that it's out of date, so that the client can display a message to the user. This time is not known in advance, though, and can't explicitly be written in the documentation.
The problem I want to solve is:
Is there an HTTP header field I should use to indicate that a certain URI will cease to work at a certain time and, if so, which?
This can't be the first time someone wants to solve this problem. Is there an unofficial header field already in use, or should I design my own? Note that I don't want to add this information to the content itself, as that would mean that every resource was changed and needs to be refreshed by the client, which is of course not what happened.
Strictly speaking, no. The resources should be driving your applications state, so if there is a change, the uri linking would provide the nessessary changes to your application.
For a HTTP header, you are free to add custom headers. Normally starting with X- but its important to know changes to uri's is only interesting to developers not users.
I am trying to access a CalDAV account in iCal and everything works fine except for the Delegation tab. I can see the account(s) I have access to (including the correct read/write properties), but the checkboxes are disabled and the calendars cannot be selected. Has anyone seen this before & know what the cause is?
This is a custom CalDAV implementation, so it is likely due to a disconnect between what iCal expects and what our server is sending -- but there are no error/warning messages in the console to indicate what the problem might be.
Any advice would be appreciated.
iCal queries the permissions and methods available on the server. To query the permissions on a collection resource you will need to have the DAV::read-current-user-privilege-set permission. Assuming iCal can read the permissions it will be looking for the DAV::read permission for reading and the DAV::bind, DAV::unbind and DAV::write permissions to indicate the ability to write.
The best way to debug this is probably to read RFC3744 about half a dozen times, interspersed with using iCal against a working server and sniffing the TCP communication as it does it. A good way is to use some kind of man-in-the-middle proxy so you can sniff the communication with (e.g.) Mobile Me or iCloud.
In my limited experience, this happens when the account used for sharing is functional (not personal) in Microsoft Exchange Server 2010. An example, where two of three are functional:
I do use various CalDAV implementations but have never encountered the same limitation, so this may be not a good answer. Also Exchange Web Services (EWS) for calendaring and delegation are probably not comparable to CalDAV. Still, it's food for thought.
The Debug menu of iCal 5.x offers CalDAV logging options.
To enable that menu, you could use the Secrets preference pane.
It is said that in a well defined RESTful system, the clients only need to know the root URI or few well known URIs and the client shall discover all other links through these initial URIs. I do understand the benefits (decoupled clients) from this approach but the downside for me is that the client needs to discover the links each time it tries access something i.e given the following hierarchy of resources:
/collection1
collection1
|-sub1
|-sub1sub1
|-sub1sub1sub1
|-sub1sub1sub1sub1
|-sub1sub2
|-sub2
|-sub2sub1
|-sub2sub2
|-sub3
|-sub3sub1
|-sub3sub2
If we follow the "Client only need to know the root URI" approach, then a client shall only be aware of the root URI i.e. /collection1 above and the rest of URIs should be discovered by the clients through hypermedia links. I find this cumbersome because each time a client needs to do a GET, say on sub1sub1sub1sub1, should the client first do a GET on /collection1 and the follow link defined in the returned representation and then do several more GETs on sub resources to reach the desired resource? or is my understanding about connectedness completely wrong?
Best regards,
Suresh
You will run into this mismatch when you try and build a REST api that does not match the flow of the user agent that is consuming the API.
Consider when you run a client application, the user is always presented with some initial screen. If you match the content and options on this screen with the root representation then the available links and desired transitions will match nicely. As the user selects options on the screen, you can transition to other representations and the client UI should be updated to reflect the new representation.
If you try and model your REST API as some kind of linked data repository and your client UI as an independent set of transitions then you will find HATEOAS quite painful.
Yes, it's right that the client application should traverse the links, but once it's discovered a resource, there's nothing wrong with keeping a reference to that resource and using it for a longer time than one request. If your client has the possibility of remembering things permanently, it can do so.
consider how a web browser keeps its bookmarks. You probably have maybe ten or a hundred bookmarks in the browser, and you probably found some of these deep in a hierarchy of pages, but the browser dutifully remembers them without requiring remembering the path it took to find them.
A more rich client application could remember the URI of sub1sub1sub1sub1 and reuse it if it still works. It's likely that it still represents the same thing (it ought to). If it no longer exists or fails for any other client reason (4xx) you could retrace your steps to see if you can find a suitable replacement.
And of course what Darrel Miller said :-)
I don't think that that's the strict requirement. From how I understand it, it is legal for a client to access resources directly and start from there. The important thing is that you do not do this for state transitions, i.e. do not automatically proceed with /foo2 after operating on /foo1 and so forth. Retrieving /products/1234 initially to edit it seems perfectly fine. The server could always return, say, a redirect to /shop/products/1234 to remain backwards compatible (which is desirable for search engines, bookmarks and external links as well).
I'm trying to develop a simple REST API. I'm still trying to understand the basic architectural paradigms for it. I need some help with the following:
"Resources" should be nouns, right? So, I should have "user", not "getUser", right?
I've seen this approach in some APIs: www.domain.com/users/ (returns list), www.domain.com/users/user (do something specific to a user). Is this approach good?
In most examples I've seen, the input and output values are usually just name/value pairs (e.g. color='red'). What if I wanted to send or return something more complex than that? Am I forced to deal with XML only?
Assume a PUT to /user/ method to add a new user to the system. What would be a good format for input parameter (assume the only fields needed are 'username' and 'password')? What would be a good response if the user is successful? What if the user has failed (and I want to return a descriptive error message)?
What is a good & simple approach to authentication & authorization? I'd like to restrict most of the methods to users who have "logged in" successfully. Is passing username/password at each call OK? Is passing a token considered more secured (if so, how should this be implemented in terms of expiration, etc.)?
For point 1, yes. Nouns are expected.
For point 2, I'd expect /users to give me a list of users. I'd expect /users/123 to give me a particular user.
For point 3, you can return anything. Your client can specify what it wants. e.g. text/xml, application/json etc. by using an HTTP request header, and you should comply as much as you can with that request (although you may only handle, say, text/xml - that would be reasonable in a lot of situations).
For point 4, I'd expect POST to create a new user. PUT would update an existing object. For reporting success or errors, you should be using the existing HTTP success/error codes. e.g. 200 OK. See this SO answer for more info.
the most important constraint of REST is the hypermedia constraint ("hypertext as the engine of application state"). Think of your Web application as a state machine where each state can be requested by the client (e.g. GET /user/1).Once the client has one such state (think: a user looking at a Web page) it sees a bunch of links that it can follow to go to a next state in the application. For example, there might be a link from the 'user state' that the client can follow to go to the details state.
This way, the server presents the client the application's state machine one state at a time at runtime. The clever thing: since the state machine is discovered at runtime on state at a time, the server can dynamically change the state machine at runtime.
Having said that...
on 1. the resources essentially represent the application states you want to present to the client. The will often closely match domain objects (e.g. user) but make sure you understand that the representations you provide for them are not simply serialized domain objects but states of your Web application.
Thinking in terms of GET /users/123 is fine. Do NOT place any action inside a URI. Although not harmful (it is just an opaque string) it is confusing to say the least.
on 2. As Brian said. You might want to take a look at the Atom Publishing Protocol RFC (5023) because it explains create/read/update cycles pretty well.
on 3. Focus on document oriented messages. Media types are an essential part of REST because they provide the application semantics (completely). Do not use generic types such as application/xml or application/json as you'll couple your clients and servers around the often implicit schema. If nothing fits your needs, just make up your own type.
Maybe you are interested in an example I am hacking together using UBL: http://www.nordsc.com/blog/?cat=13
on 4. Normally, use POST /users/ for creation. Have a look at RFC 5023 - this will clarify that. It is an easy to understand spec.
on 5. Since you cannot use sessions (stateful server) and be RESTful you have to send credentials in every request. Various HTTP auth schemes handle that already. It is also important with regard to caching because the HTTP Authorization header has special specified semantics to caches (no public caching). If you stuff your credentials into a cookie, you loose that important piece.
All HTTP status codes have a certain application semantic. Use them, do not tunnel your own error semantics through HTTP.
You can come visit #rest IRC or join rest-discuss on Yahoo for detailed discussions.
Jan