Skip to main content

Services & Artifacts

As explained in Why reShapr?, reShapr ingest your API’s existing artifacts such as OpenAPI 3.x specs, GraphQL schemas and gRPC/Protobuffer definitions to discover Services and create MCP Servers. A Service in reShapr represents a functional service promise - for example a User Management Service with a specific version - for example 1.0 - made of several operations (searchUsers, getUserById, etc...). Service are versioned so you’ll be able to handle the different versions of the User Management Service which can be 1.0, 1.1, 2.0 and so on…

Your first steps with reShapr will certainly be to import new artifacts into the system so that reShapr can discover and propose Services to expose. As of today, this task is realized using the reShapr CLI that holds the reshapr import tool. But before diving into the Getting Started guide, let’s review the information and conventions reShapr is using from these specifications.

  • When importing an OpenAPI 3.x artifact, reShapr will naturally use the info.name and info.version that are mandatory elements in the specification. The discovered Service will then naturally have this name and version,
  • When importing a gRPC/Protobuffer definition, reShapr will look for a Protocol Buffer service definition and will return the first it finds. reShapr will also look at the package directive. This package information will be used for two purposes: to provide a full name for the reShapr service that will be <package>.<serviceName> and to extract the version information. As it’s a best practice to put the version as the last element of a package name in gRPC, reShapr will use the last element as the version.
  • When importing a GraphQL schema, things are a bit different because Graph Schema doesn’t have a way to provide information on the service name or version. So when importing a GraphQL schema in reShapr, you will have to explicitly provide the serviceName and the serviceVersion you want this service to be registered as.

As Services are versioned in reShapr, the direct consequence is that reShapr will be able to keep many different versions of the same Service in parallel. It will be then up to you to manage the expositions of version 1.0, then version 2.0 etc. When a version of a service is no longer of importance for you, you can delete it - but it will automatically remove existing expositions.

Updating a Service in reShapr is a trivial process ; it simply means re-importing its reference artifacts. If its service name and version are already present in reShapr, the definition will be updated. If not, a new Service entry will be created and attached to your account.

Agent View