index.md

Contents

• Design guidelines
  • Allegro REST API
    • What is RESTful API interface?
    • What is Developer Experience?
• Resource
  • Name
  • Identification (UU)IDs
  • URLs for user's collections
  • Lowercase paths
  • Minimize resources nesting
  • Beta resources
  • Versioning
    • Beta version
  • Views
  • User Agent Header
    • Identifying your client
  • Use HTTP methods to operate on collections and entities
    • Update and create must return a resource representation
    • Create entity
    • List entities (collection)
    • Get selected entity
    • Update entity
    • Delete entity
  • Return appropriate status codes
  • Validate request parameters
    • Validate errors
    • Validate selected fields
• Representation
  • Property name format
  • Provide resource (UU)IDs
  • Null values
  • Use UTC times formatted in ISO8601
  • Time without date
  • Country, language and translations
    • Value representation
    • Translations
  • Price and currency
  • Enum values
  • Nesting foreign resources relations
  • Provide full resources where available
  • Accept JSON in request bodies
  • Keep JSON response minified
  • Filtering
    • Simple filters in query string
    • Filter by multiple values in one filed
    • Advanced filtering (similar to search) concerning many parameters and nested structures
  • Sorting
  • Wrap collection in object
  • Consistent paging scheme
  • Keep response gziped
• Error
  • Provide Trace-Ids for Introspection
  • Generate structured errors
• Command pattern
  • Problem
  • Solution
    • Adding the command
    • Checking execution status (optionally)
  • Antypatterns replaced by this pattern
• Documentation
• Glossary
  • General
  • Address
  • Image
  • Description
  • Category
  • User
  • Coordinates
  • Pagination
  • Try to avoid
• HATEOAS