Difference between revisions of "OpenStack-SDK-PHP/TechnicalRequirements"
(Created page with "== Requirements == === Top-level objectives === ==== Ease of installation ==== * Composer/Packagist package * PHAR file * PEAR package? * Linux distro package? (Yum, apt-ge...") |
Matt Farina (talk | contribs) (→Ease of installation) |
||
Line 5: | Line 5: | ||
==== Ease of installation ==== | ==== Ease of installation ==== | ||
− | * Composer/Packagist package | + | * Composer/Packagist package (Priority 1) |
− | * PHAR file | + | * PHAR file (Priority 2) |
− | + | ||
− | + | PEAR and Linux packages are not currently part of the requirements. If someone believes one of them should be handled please file a blueprint and make a case. | |
==== Ease of use ==== | ==== Ease of use ==== |
Revision as of 15:41, 7 March 2014
Contents
Requirements
Top-level objectives
Ease of installation
- Composer/Packagist package (Priority 1)
- PHAR file (Priority 2)
PEAR and Linux packages are not currently part of the requirements. If someone believes one of them should be handled please file a blueprint and make a case.
Ease of use
- Human-readable service names: minimize usage of OpenStack codenames
- Well-written and highly accessible end-user documentation that strives to be as comprehensive and helpful as possible
- Assumption-free documention, capable of expressing a concept soundly to both novices and experts
- Consistent use of code samples
- API documentation
- PHP docblock annotations
- A simple API that minimizes complexity and vendor differences
Ease of contributing
- Community-driven decisions with full feedback and transparency
- A CONTRIBUTING guide, encouraging all forms of engagement
- Active on irc channels
- A mailing list
- Google Hangout meetings
Technical requirements
HTTP transport layer
- Support for all HTTP request methods, including custom ones
- Requests, responses, headers and URLs can be easily accessed and editable (i.e. they serve as objects)
- Persistent connections
- Connection pooling
- Parallelization with multi-cURL
- Request bodies are handled as streams rather than strings - to avoid in-memory storage
- Ability to register a Swift stream wrapper, so that native filesystem functions can be utilized
- Perhaps the ability to use `swift://` protocol
- Flexible authentication
- Auth caching
- Multiple connection types offered through adapters: cURL, sockets, test/mock
- Redirect handling
- SSL support
- Retry strategies (in response to cURL/HTTP errors, throttling, etc.)
Service layer
General
- Support for multiple service versions, easily selected by an end-user
- The core library will contain common functionality essential to the running of a pure OpenStack installation
Extensions
- Extensions, whether vendor-specific or not, need to be handled appropriately. There is a strong argument for extracting this supplementary functionality from the core library and placing it in other namespaces (or repositories)
- Discussion point: Need to agree where to place / how to structure vendor extensions
Service clients
- Discussion point: Need to agree whether each service will act as its own client, or whether a more global context will be used.
- Discussion point: Need to agree the best way to define API services (json-schema, Guzzle DSL, userland code)
- Discussion point: Need to agree the best way to create or marshall service objects from their descriptions - i.e. some form of service container
API concepts
- We should objectify and properly abstract the basic concepts of a ReSTful API. For example: a service is composed of Resources
- Each resource has state and is expressed through properties.
- Discussion point: How strict should we be with API resource properties?
- Each resource can be modified with ReSTful operations. Each operation is composed of the following:
- A HTTP method
- A URL (absolute or relative)
- Parameters (key/val array)
- A description
- A definition of how its response will be parsed
- Each resource has state and is expressed through properties.
Miscellaneous
Events
- We should use Event dispatching to expose all moments of a request's lifecycle to the end-user. This allows them to add in or modify functionality as it suits them, rather than them having to extend and override main classes.
- We should think about what "events" are most important for an end-user: request.before_send, request.sent, request.error, curl.progress, etc.
Iterators
- We should support iterators and request-based append functionality.
- We should make this as consistent as possible and hide any underlying inconsistencies.
- We should also utilize native SPL iterators where possible.
Waiters
- Ability for users to "wait for" an operation to achieve some state. For example, a user may want to wait until a Nova instance has finished building before continuing with their script.
- This should be easy for an end-user to work with
Error handling
- Error messages need to be as descriptive and helpful as possible. We should not expose them to an API message or HTTP status code.
- Discussion point: Need to agree about how to use exception classes
Workflow/methodology
Standardisation
- PSR-2 coding style
- PSR-3 logging interface
- PSR-4 autoloading
Documentation
Discussion point: Need to discuss what technology or tooling we will use to write our end-user documentation - i.e. Sphinx, markup Discussion point: Need to decide how to host our documentation - i.e. Read the Docs or OpenStack domain
Testing
Methodology
Discussion point: Need to decide our testing methodology.
Tooling
Discussion point: Need to decide our testing tool.
Continuous integration
- Travis?