mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-12 12:06:29 +03:00

Files

T

Magnus HedemarkandGitHub c7c4d3b74f Port 11 methodology skills from hermes-profiles (#69 )

Engineering: backend-engineering, frontend-engineering, data-engineering,
ml-engineering, platform-engineering, qa-methodology

Executive: go-to-market, legal-strategy, operational-design, org-design,
product-strategy

ml-engineering: added missing training-infrastructure.md reference
qa-methodology: added test-data-management, performance-testing,
security-testing references

All frontmatter converted to agent-skills convention.
Source: https://github.com/magnus919/hermes-profiles

2026-07-21 00:58:26 -04:00

2.2 KiB

Raw Blame History

API Patterns

Endpoint Design

Aspect	REST	gRPC	GraphQL
Resource modeling	Nouns as resources, verbs as methods	Services with RPC methods	Schema-defined types and queries
Request structure	Path params, query params, headers, body	Protobuf messages	Query/mutation with variables
Response structure	JSON with envelope	Protobuf messages	Shape matches query structure
Error reporting	HTTP status codes + error body	gRPC status codes + details	Errors in `errors` array
Versioning	URL path or header	Package version in proto	Schema evolution with deprecation
Pagination	Cursor-based preferred	Token-based in proto args	Connection/edges pattern (Relay)

Versioning Strategies

Strategy	Mechanism	Breaking change handling
URL path	`/v1/resources`, `/v2/resources`	New path, old path maintained
Header	`Accept: application/vnd.api+json; version=2`	New accept header value
Query param	`?version=2`	New param value, old default maintained
No versioning	Evolve in place with additive changes	Only additive changes permitted

Prefer URL path versioning for public APIs — it's the most visible and least ambiguous.

Pagination

Strategy	Pros	Cons	Best for
Cursor-based	Stable under writes, no offset drift	Opaque cursors, can't jump to page N	Real-time data, feeds
Offset-based	Simple, can jump to any page	Skips/duplicates on writes	Static datasets, admin UIs
Keyset	Fast, stable	Requires sort key, complex multi-column	Large datasets, ordered data

Always include pagination metadata: {data: [...], next_cursor: "...", has_more: true}.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is malformed.",
    "details": [
      {"field": "email", "reason": "must be a valid email address"},
      {"field": "age", "reason": "must be a positive integer"}
    ],
    "request_id": "req_abc123"
  }
}

Every error response should include: machine-readable code, human-readable message, request ID for tracing, and structured details for programmatic handling.

2.2 KiB Raw Blame History