How To - Register a Service
From The Socknet
Any service can register with a user in order to setup access to functions on their provider. In many cases, this is not necessary, but expediates future communications.
Contents |
Example of when registration is useless
If UserA comments on UserB's blog, http://myblog.com/, that blog may attempt to post a message to UserA's provider about that comment. This activity might never be repeated again. In this case, it is not useful to register this service.
Example of when registration is useful
Clearly UserB should register his own blog. Anything that is used frequently should consider registering with the user.
Unregistered services must already be interacting with the user when they want to post something, so that they can redirect the user to an approval page. Registered services can post without extra approval. They are also discoverable by other services.
Delayed posting
Another type of service that needs registering is one that posts messages without direct user action. Services that use delayed mechanisms must register with the user's provider.
How it is done: Example
UserA signs up on http://photosite.com.
http://photosite.com wants to register with UserA because it believes it will be used frequently to host photos. It POSTs to UserA's register-service function:
POST register_service
{ from: { serviceid: "http://photosite.com/agents",
protocols: { "http://photostandards.com/photoxchange":
{ public_data: ... anything at all ...
}
}
},
notification: true,
return: "http://photosite.com/UserA/registration-complete"
}
If for some reason the provider already thinks photosite is acceptable or unacceptable to the user it responds with:
->
{ accepted: boolean
}
If it was accepted, the provider should replace old protocol data with new protocol data.
Otherwise, the response is:
->
{ redirect: "http://provider1/user1/verification/1442512"
}
The service should send the user to the URL given. When the user has made a decision, he will be sent back to the return URL specified in the request.
Verification URLs are assumed to be valid for only a short amount of time, on the order of minutes.
Protocol Data
During registration a Service can indicate what protocols it supports and include some data that other Services may find useful (generally contact information related to that protocol).
The data is later passed on in Service Discovery.
Notification
The notification field indicates that the service would like to receive automatic forwards of messages to or from the user. The provider is permitted to ignore this option or restrict the items that are sent. Providers SHOULD only forward items which would be automatically forwarded to the user's friends. This usually corresponds to the items which would show up on the user's profile.
Notification is accomplished through the use of the service's notify-message function, so the service must support the Socknet API.
Unregistering
Unregistering is important when a service plans to go offline. It is available at any time without the user's permission. It uses the unregister-service function:
POST unregister-service
{ from: { serviceid: "http://photosite.com/agents" }
}
The provider will verify the service like always and if all checks out, wipe the service's information from the user's records. Later, if the service's domain changes hands, the new owner won't be able to access user data.
Considerations
It's a Good Idea™ to tell the user that a service is gone when it unregisters.
In the future, the registration may include a "private_data" field. This will allow the service to store and retrieve data that is only visible to itself (and the user, if he cares). This is kind of like a cookie. It will have variable size. We'll need to get feedback to see if this would be a desirable feature.
