# GNOME Online Accounts Overview

## Writing GOA applications

The term GOA application is used to describe applications or libraries that are using the GNOME Online Accounts D-Bus APIs either directly or through the supplied client library.

### Account Objects

A GOA application typically creates #GoaClient object to get a list of accounts and listen for changes. Each account provide one or more specific services (such as mail, calendaring or contacts) so the application will need to set up a filter for the services it is interested in. For example, a mail application would only be interested in GOA accounts with mail- and contacts-services, not accounts with calendaring-services. Applications can use methods on the #GoaObject type (such as goa_object_peek_mail()) to check what kind of services an account provides. Note that this list can change at run-time if e.g. the user toggles a Use account for Mail check-button.

Applications may use the Account.Id property as a unique key to store information obtained from an account.

Applications must not destroy data if an account object is removed (e.g. when the #GoaClient::account-removed signal is emitted) - for example, if the `goa-daemon` program crashes or is restarted on software upgrade, account objects will be removed only to be added back the next time `goa-daemon` is started.

Applications should use the Account.ProviderIcon, Account.ProviderName and Account.PresentationIdentity properties when presenting an account in an user interface. For example, for a hypothetical online services provider Acme, this would be the Acme Logo, the word "Acme" and the identity could be either an email address such as some.name@acme.com or an user handle such as `davidz25` or `chunkylover53`.

### Accessing Services

A GOA application needs to handle service-specific protocols and quirks itself. Some service-types, such as mail, may use standard protocols such as IMAP or SMTP but they also may not. GOA applications should always look at the Account.ProviderType property to infer what kind of protocol and endpoint to use.

### Credentials Handling

For accessing a service, the application typically needs to present credentials. The application can request the credentials via GOA. First the application should invoke the Account.EnsureCredentials() method on the account object. If this succeeds, the application can request the credentials using e.g. OAuthBased.GetAccessToken() or OAuth2Based.GetAccessToken() depending on what kind of credentials the account is using. If the service returns an authorization error (say, the access token expired), the application should call Account.EnsureCredentials() again to e.g. renew the credentials.

On the other hand, if Account.EnsureCredentials() ever fails, then the user will get notified that there is a problem with the account so he can take actions to fix it. Applications can listen to changes on the Account.AttentionNeeded property to get notified when it's time to try accessing the account again.

Note that the implementation for a provider may switch from e.g. OAuth to OAuth2 in a newer release of GNOME Online Accounts. Therefore, applications must never assume that the #GoaObject for an account implements a fixed set of interfaces.