#### Overview [src]

## 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 provides one or more specific services (such as `GoaMail`, `GoaCalendar`, `GoaContacts`) 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 `GoaAccount: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 `GoaAccount:provider-icon`, `GoaAccount:provider-name` and `GoaAccount:presentation-identity` 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`.

### Accessing Services

A GOA application needs to handle service-specific protocols and quirks itself. Some service-types, such as `GoaMail`, may use standard protocols such as IMAP or SMTP but they also may not. GOA applications should always look at the `GoaAccount:provider-type` 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 `goa_account_call_ensure_credentials()` method on the account object. If this succeeds, the application can request the credentials using e.g. `goa_oauth_based_call_get_access_token()` or `goa_oauth2_based_call_get_access_token()` 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 `goa_account_call_ensure_credentials()` again to e.g. renew the credentials.

On the other hand, if `goa_account_call_ensure_credentials()` 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 `GoaAccount:attention-needed` 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.