I was a bit confused by the Role vs App vs Service thing as well initially. If my understanding is flawed, I'll defer to more experienced users.
Service: A Rest endpoint serving as the gateway to a service (code or database) that is exposed to the world. Services don't know about security, only what methods/data they expose.
App: A way of controlling permissions across multiple services so a single application can consume aspects of many APIs. An application is a "way of using the api" - could be any interface or usecase. An app could access a part of one API or many APIs. I believe apps can also be used for tracking/auditing usage and controlling rates in some editions.
Role: A way of controlling levels of service within an app. Each app can have a default role, and each user (or group of users) can be assigned another role in the app.
For a concrete example, think about an enterprise application for managing invoices.
First, you have Services, here are 3 plausible ones for this application:
- Handle scanned invoice I/O (an FTP service that also writes to a DB. Stores and retrieves invoices)
- Make payment for an invoice (a custom script to make payments)
- Report on invoices (a db service)
Now, the enterprise would have many more services than that. HR has their services, Legal has services, etc.
The App limits access to the three services above. This is done by providing the developers of the app with the API key.
Now, Audit doesn't need to make payments, but they need to be able to look at invoices and report on them. The Audit Role is granted permissions to those tables, so when they use the Invoice App, they will be able to do a certain set of actions. If they use another app, they would be able to do audit-ish things in that app too.
Scanners have another role - they can only post to scanned invoice service, not read from it. This can also be controlled with a role.
I hope that makes sense!