Suggest modification to this talk

Title

Description

So you've just added a suite of RESTful APIs to your web service. Now you need to generate documentation and build Ruby, Python, and JavaScript clients to consume those new APIs. With so many moving parts, how do you keep your service, documentation and clients in sync?
We all know how to describe data using ActiveRecord models. Have you considered using a model to describe your service?
A service model provides a number of benefits including: easy to generate API documentation, consistent server side parameter validation, versioned APIs, easy to build clients, and more. It also represents a unified view of your API which helps to keep your code and documentation DRY. But what does a service model look like? For instance, did you know that your APIs can be described using just four parameter types? What if your could express your APIs using a Rails DSL?
This talk will introduce Seahorse, a DSL for describing API operations for just about any web service. It provides all of the above functionality, allowing you to describe your service model in a single place with Ruby code. We will demonstrate how to use Seahorse to generate clients, model existing real-world APIs, and even build one of our own

Help us caption & translate this video!

http://amara.org/v/FGaP/

Date

Summarized using AI?

If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.

Show "Summarized using AI" badge on summary page

Summary

Markdown supported

In the talk "Describing Your World with Seahorse," Trevor Rowe from Amazon Web Services presents the significance of service models in web services, especially in the context of building APIs using Ruby and Rails. He emphasizes that an API should be treated as a first-class entity rather than a mere side effect of data persistence. Here are the key points discussed:

- **API as an Entity**: APIs should be designed from the customer's perspective, focusing on what the API needs to deliver rather than how data is stored in the database.  
- **Need for API Models**: Without a distinct API model, developers face duplicated efforts in filtering parameters, generating API documentation, and managing API versions. An API model facilitates the organization of this process and lays groundwork for efficiency.  
- **Introduction to Seahorse**: Seahorse is described as a Domain Specific Language (DSL) that allows developers to define the structure of web service APIs. It streamlines the process of generating API documentation, validating server-side parameters, creating versioned APIs, and building clients across multiple languages (Ruby, Python, etc.).  
- **Seahorse DSL Features**: It includes features like defining parameter types, managing complex types (maps, lists, and structures), and supporting metadata for better documentation generation.  
- **Generating Documentation**: Seahorse uses metadata to create API documentation that dynamically matches the service definitions. This eliminates discrepancies that can arise from manually maintaining documentation alongside the codebase.  
- **Dynamic Client Generation**: Clients for APIs can be automatically generated using the Seahorse models, reducing the need for manual coding and helping ensure consistency across different platforms.  
- **Evolution of Parameters Handling**: Rowe discusses the transition from attribute-accessible patterns in Rails to strong parameters and critiques the limitations of strong parameters regarding type safety and flexibility. He positions Seahorse as a promising alternative capable of enforcing better type-management and metadata handling.  
- **Call to Action**: Participants are encouraged to explore Seahorse for building robust and scalable APIs while noting that this tool is still in development and requires future enhancements. Finally, Rowe invites questions and highlights available job opportunities at AWS.

Overall, the talk underlines the importance of a unified approach to API design, where Seahorse plays a pivotal role in enhancing consistency, clarity, and efficiency in API development.

Cancel