Friend List API
Model invitations, accepted connections, blocking, and visibility as distinct rules rather than one unrestricted array.
Start with the record.
Keep what matters.
A friend list API describes relationships between accounts, not simply a collection of profile cards. A pending invitation, an accepted connection, a removed relationship, and a blocked account have different meanings. A careful design keeps those states explicit and decides who may see each relationship in each context.
A simple field model
These illustrative fields are a starting point for your own design. They are not a live ListAPI.com API contract and should not be substituted for a provider’s documented request format.
| Illustrative field | What it should tell you |
|---|---|
relationship_id | The durable identity of a connection or request. |
participants | The account identities involved in the relationship. |
state | Pending, accepted, removed, or another defined state. |
visibility | Who may see this relationship in a particular context. |
A useful starting point
A mutual friendship is different from a one-way follow, a saved contact, or membership in a group. Define which relationship the application supports and what creates it. For mutual friendship, an invitation and acceptance may be separate operations. A following model may be directed, with one account following another without a reciprocal relationship.
Avoid using one generic array for every connection type. A person can follow someone, share a group with them, and still not be their friend. Keep those relationships distinct so visibility and notification rules can differ. This also prevents a later feature from interpreting a weak connection as authorization to reveal information intended only for accepted friends.
Before you connect the list
Identify the source of truth and the intended audience. Start with a small read-only view so you can compare the result with the source. Record the retrieval scope and keep incomplete imports visible instead of treating a partial result as the whole collection.
Choose how to handle a renamed record, a repeated request, a removed item, and lost access. Make field ownership explicit before adding two-way edits. The full guide explores the decisions specific to this list type and links to an official reference.