3.3.2.Practices for Resource Names, Actions & Associations

• Resource Identity

  • API endpoint or URL for the resource

    • 1.Avoid using your www domain for API e.g., http://www.acme.com

    • 2.Keep your base URL simple

    • 3.If possible use a subdomin e.g., https://api.twitter.com

    • 4.Or/And use seperate domain e.g., https://api.walmartlabs.com

• Resource names

  • Use nouns to identify the resources

  • Use of Plural is suggested

    • e.g., Walmart: /items, /items/{id}

    • e.g., Linkedin: /people, /people/{id}

  • Do not use verbs for resources

    • e.g., Do not use /getVacationPackages

    • GET http://api.acme.com/vacations

    • GET, PUT, DELETE, POST http://api.acme.com/vacations/{id}

• Action

  • Action operation != CRUD

  • OK to use action as part of resource hirarchy e.g., /friendships/lookup

  • Or create an action with subquery e.g., /search?query

• Associations

  • Resources contain other resources

  • e.g.,

    • Facebook /me/photo

    • Walmart Items/{id}/reviews

    • Twitter mutes/users/list

  • Avoid deep nesting (Maximum = 3 suggested)

  • Use subquery to avoid deep nesting