@muze-labs/metro-solid
v0.1.0
Published
A Solid resource and container API helper for Metro clients.
Readme
Solid API
Solid API is a Metro API helper for Solid resources and containers.
Milestone status: Milestone 1 core is implemented.
It handles Solid resource and container operations, header helpers, safe write options, linked-data parsing through metro-oldm, and minimal Solid discovery. solidApi(base, methods) returns a Metro API object, where base can be a URL string or an existing Metro client.
For applications, solidApi() is the preferred entry point. Libraries that need to extend Solid API behavior can compose their own Metro client and call new metro.API() inside their own factory method.
It does not handle authentication, file-system APIs, OLDM object modelling, or application conventions.
Docs:
import { solidApi } from '@muze-labs/metro-solid'
const solid = solidApi('https://pod.example/', {
async storageFor(webId) {
return this.discoverStorage(webId)
}
})
await solid.get('notes/hello.txt')
await solid.put('notes/hello.txt', {
body: 'Hello',
headers: { 'Content-Type': 'text/plain' }
})
await solid.create('notes/new.txt', 'Hello', { headers: { 'Content-Type': 'text/plain' } })
await solid.createContainer('notes/')
const created = await solid.postToContainer('notes/', 'Hello', {
headers: {
Slug: 'hello.txt',
'Content-Type': 'text/plain'
}
})
console.log(created.location)create(url, body, options) and createContainer(url, options) send If-None-Match: * by default so callers can create without overwriting an existing resource. Use put() when replacement is intentional.
Metro style
Solid API follows the current Metro style:
solidApi()is the factory function, likemetro.jsonApi();- it returns a
metro.APIobject; - it accepts the same base URL plus methods style as
metro.jsonApi(); - it adds
metro-oldmautomatically; - generic HTTP methods return Solid API data objects for successful responses;
- its Solid-specific helpers call the API object's own Metro verb methods;
- it does not define its own HTTP error type.
General linked-data reads return the parsed OLDM result. That result may be a graph or a collection of subjects and does not need to have a primary subject. Profile discovery is stricter: a WebID identifies one subject and must be a fully qualified URL, so discoverProfile(webId) returns that subject directly or throws.
Add authentication middleware to the base Metro client when requests should authenticate.
Successful Solid API calls return parsed linked-data objects. Empty successful responses become {}. The original response is attached as non-enumerable metadata for Solid helpers that need headers, so response data must be object-shaped when that metadata is present. postToContainer() exposes Solid creation headers directly:
const created = await solid.postToContainer(url, body, { headers: { Slug: 'note.ttl' } })
created.response.status // HTTP status from Metro
created.location // Location response header
created.etag // ETag response headerDiscovery
Solid API consumes linked data parsed by the metro-oldm middleware it installs:
const profile = await solid.discoverProfile(webId)
const info = await solid.discoverWebId(webId)
profile.id // the WebID subject
info.storage // storage root URLs
info.issuer // Solid OIDC issuer URL, if present
info.inbox // LDP inbox URL, if presentUse the parsed profile subject directly when you need profile-specific predicates that are not exposed by discoverWebId().
Storage discovery expects the pim prefix used by the default OLDM context, so profile data should expose pim$storage.
Solid API does not parse Turtle itself; it delegates that to metro-oldm.
Container membership also consumes parsed linked data from the response:
const entries = await solid.contains(storageUrl)
entries[0].url // contained resource URL
entries[0].resource // parsed ldp:contains itemBoundary
metro
generic HTTP
metro-oidc
authentication/session middleware
metro-oldm / OLDM
linked-data parsing and writing
solidApi
Solid HTTP affordances